Can I do some sweeping changes to rule docs?

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.

• Correct styling example - background color and icons give clear visual cues as to whether the block is showing acceptable or unacceptable patterns
• Incorrect styling example - no background color or icon

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?

[guerrero]

Great @ilyavolodin! I’ve created a PR 😃

[nzakas]

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).