Stuck on an issue?

Lightrun Answers was designed to reduce the constant googling that comes with debugging 3rd party libraries. It collects links to all the places you might be looking at while hunting down a tough bug.

And, if you’re still stuck at the end, we’re happy to hop on a call to see how we can help out.

Can I do some sweeping changes to rule docs?

See original GitHub issue

Now that I’ve got the hang of doing commits, I’d like to do some further refinement of docs to make them more consistent, comprehensible, etc. Here’s some things I’d like to look in to…

1 - Proper styling of good vs. bad code examples

There are styling discrepancies in the example code blocks in the rules documentation.

I’d like to check through every rule doc and ensure it’s using correct styles as this makes a big difference in readability IMO.

2 - Standardise text appearing above example code blocks

The wording appearing above example code blocks varies quite a lot throughout the rules docs.

Some examples of the wording used for “correct/acceptable” example blocks:

  • Examples of correct code for this rule with the “always” option:
  • The following patterns are not considered problems:
  • When using “after” this spacing will be enforced:

The first one (Examples of correct code for this rule with the “always” option:) is the most widely used format.

However, do we even need that text above code blocks? If we have icon and background color giving visual cue, and the option syntax is in a code comment on the first line of the code block, the text above the code block is somewhat superfluous/redundant?

3 - Ensure each pair of code blocks has a suitable heading

There are some rules docs that don’t use proper headings above pairs of code blocks, resulting in a somewhat unreadable document structure (not to mention preventing linking to the examples for a particular option). I’ll make sure headings exist, optionally with a brief summary of what the option is about below the heading.

4 - Tidy up the Options summary section

Some of the options summary sections are difficult to read and use different layouts, etc. I’d like to make them all more consistent, in particular:

  • Consistent documentation pattern for summary section
  • Make it much more obvious what the defaults are
  • Include examples of the .eslintrc syntax (facilitate easy copy and paste)
  • Hyperlink each option to associated example code blocks
  • Flag any rules that have cumbersome options (propose alternatives for review)

5 - Additional cleanup of the opening sections

I feel the opening sections could benefit from a refactor. This step would start with mocking up the proposed layout and documentation pattern in the wiki, allowing rapid prototyping to get an acceptable format, then each rule doc would be updated to the new structure.

Note: This could cause some breaking changes (eg. links to headings or the quick search bar).

6 - Experiment with more compact code example layouts

Having full-width code examples in a vertical column results in very long scrolling pages. I’d like to experiment with putting code blocks side by side (eg. using flexbox or a grid layout) - the blocks would return to vertical layout on smaller screen sizes.

I’d also like to experiment with collapsible sections, maybe using something like jquery to expand/collapse the code samples.

7 - Folksonomy (tags/labels)

I’d like to explore tags/labels as an alternate to rule categories. For example, tags could be like: #whitespace, #es6, #arrow-functions, #deprecated, etc.

This could potentially replace the Related Rules section that appears on some pages; user can just click a tag to see all rules associated with that tag.

The dictionary of tags would be centrally defined and then each rule source code would have tags added to it’s exports (or something like that?). Part of the docs site build process would then generate tags index pages, etc., or alternatively have a dynamic page that loads a json object and then let user choose different views (taxonomy, folksonomy, order alpha vs. npm popularity, etc).

Anyway, those are just some things I’d like to look in to and contribute to the project. Comments?

Issue Analytics

  • State:closed
  • Created 7 years ago
  • Reactions:2
  • Comments:24 (24 by maintainers)

github_iconTop GitHub Comments

guerrerocommented, Nov 24, 2016

Great @ilyavolodin! I’ve created a PR 😃

nzakascommented, Jun 17, 2016

Just a note - let’s please leave third-party rule documentation considerations out of this discussion. There’s a giant unanswered question around discoverability of plugins and plugin rules, and I don’t want that to derail this discussion.

Regarding wording, I think “Correct code for this rule” and “Incorrect code for this rule” implies that the examples are all-inclusive, which is not true. We try to give some representative examples of what’s correct and what’s incorrect, but we can’t promise that these examples cover every case. So, IMHO, I think “Examples” is a necessary word to make that clear. I do like @aubergine10’s suggestion of “Invalid patterns” and “Valid patterns” as well (“correct” and “incorrect” always seemed a bit confusing to me).

Read more comments on GitHub >

github_iconTop Results From Across the Web

Pending Rules and Forms Amendments | United States Courts
Pending Rules and Forms Amendments. Any change to the federal rules must be designed to promote simplicity in procedure, fairness in administration, the...
Read more >
Sweeping Changes to Uniform Rules for the Supreme Court ...
Effective Feb. 1, 2021, New York's Uniform Rules for the Supreme Court and County Court will see sweeping changes. A product of the...
Read more >
Sweeping Changes to Rules of Civil Procedure
The Act provides that the court “shall” limit discovery if the burden or expense of providing the discovery outweighs its likely benefit, or...
Read more >
Sweeping Amendments to Michigan Court Rules to Take ...
Sweeping Amendments to Michigan Court Rules to Take Effect January 1, 2020. This week marked the most fundamental change in Michigan law in ......
Read more >
Additional Background:Sweeping Regulatory Changes ... - CMS
CMS is issuing a sweeping array of new rules and waivers of federal requirements to ensure that local hospitals and health systems have...
Read more >

github_iconTop Related Medium Post

No results found

github_iconTop Related StackOverflow Question

No results found

github_iconTroubleshoot Live Code

Lightrun enables developers to add logs, metrics and snapshots to live code - no restarts or redeploys required.
Start Free

github_iconTop Related Reddit Thread

No results found

github_iconTop Related Hackernoon Post

No results found

github_iconTop Related Tweet

No results found

github_iconTop Related Post

No results found

github_iconTop Related Hashnode Post

No results found