Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Can I do some sweeping changes to rule docs? #6444

Closed
originalfoo opened this issue Jun 16, 2016 · 24 comments
Closed

Can I do some sweeping changes to rule docs? #6444

originalfoo opened this issue Jun 16, 2016 · 24 comments
Labels
accepted There is consensus among the team that this change meets the criteria for inclusion archived due to age This issue has been archived; please open a new issue for any further discussion documentation Relates to ESLint's documentation enhancement This change enhances an existing feature of ESLint needs bikeshedding Minor details about this change need to be discussed

Comments

@originalfoo
Copy link
Contributor

originalfoo commented Jun 16, 2016

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?

@eslintbot eslintbot added the triage An ESLint team member will look at this issue soon label Jun 16, 2016
@pedrottimark
Copy link
Member

@aubergine10 Welcome to ESLint!

Can you compare your list to #5446 and then you and @scriptdaemon and I can coordinate our efforts?

We are at the point of needing to turn that issue into an actual doc for contributors.

@pedrottimark
Copy link
Member

We are working down the rules index by section in pull requests of 5 to 10 docs.

The most likely place for you to start will be the rules under ECMAScript 6

Am going offline now, but I will study the 7 points first thing tomorrow. This is good news!

@ilyavolodin
Copy link
Member

@aubergine10 We would be thrilled to have another person working on documentation. Could you work with @pedrottimark he is our residential documentation guru and in the process of updating our documentation now with the help from @scriptdaemon

@originalfoo
Copy link
Contributor Author

originalfoo commented Jun 17, 2016

Yup, I'll read through #5446 and related issues in the morning. I'm willing to invest a lot of time helping with documentation.

@pedrottimark - In relation to the level 2 headings and general doc structure, IMO it would be worth mocking up some pages in the wiki to try out different layouts and ideas before investing too much time in the refactoring process.

BTW, longer term, it would be nice if the website also included 3rd party rule plugins (even if just a link to them). An example is the Grunt website which lists both core plugins and also 3rd party plugins in one place - makes discovery of plugins much easier.

Random thought: I'd love it if the options syntax was rendered as interactive UI... checkboxes and drop-downs to choose options, with code samples updating in realtime giving live feedback (like jshint homepage) as to the effects of the options, and a 'copy to clipboard' link to get the .eslintrc or inline comment for the chosen config. Such an approach could drastically reduce the verbosity of pages, whilst also providing users with a great way to get the right options for their project.

@ilyavolodin
Copy link
Member

RE: 3rd party rules documentation. We haven't thought of that yet, but it might be possible if they update their rules to new rule format with metadata. We could modify metadata to include URL for documentation for each rule and collect that documentation at deploy time, or even at runtime through JS.

Interactive UI - that's what demo is supposed to be. Please keep in mind we are limited by markdown. We can't do really interactive features because of that. We also want to keep format of the documentation to bare minimum to not create unnecessary roadblocks for PRs. If it takes longer to figure out format and rules of the documentation file then to make code change, that's not a good setup.

@originalfoo
Copy link
Contributor Author

Aside from contribution complexity, are there other factors which mandate the use of markdown?

@ilyavolodin
Copy link
Member

That's the most common language for OSS documentation, as far as I know. Also built-in Github support for displaying it.

@scriptdaemon
Copy link
Contributor

scriptdaemon commented Jun 17, 2016

The more eyes on the docs, the better (as there are a lot of them).

Just a quick note just so you're aware: A lot of the docs are still in the process of being updated, so that would address at least one of your points about inconsistencies. I've been working on updating the examples and other minor updates, but I've been pretty busy the last few weeks so I haven't been able to focus as much time as I'd like. The next batch in "Stylistic Issues" should be ready soon.

@pedrottimark
Copy link
Member

@aubergine10 It is very helpful for us to see the site through your eyes.

Thank you for such clear points. It is very helpful that you described what is the problem and then recommended how to solve it. And bonus points for asking, can I…?

  1. Amen. Style that guides people quickly to a relevant example is top priority.
  2. Related to the comments by you and Ilya about third-party plugins and markdown as common language for contributors, you might think of the style as a progressive enhancement of the grammar of the example sentence. A replacement rule during site generation adds a class attribute to paragraphs that whose text matches a set of phrases at the beginning of these sentences.
    • Therefore, third-party plugins can follow the example (pardon the pun :) to distinguish the pairs of examples clearly even if you view a rule doc as ordinary markdown in a github repo.
    • The goal of explicit sentences is to clearly explain the meaning of example code for new visitors, especially if English is not their first language.
    • The goal of an obvious relationship between wording and style is for repeat visitors to quickly train their eyes to scan for the style and mostly ignore the wording. The infamous red-green color distinction pushed us to also display a thumbs down/up icon so people who have color vision deficiency have something to scan for.
  3. Amen. These are a work in progress.
    • Headings are important for scanning.
    • Heading provide useful anchors for links. However, we still need a pattern for boolean options that have pairs of examples for both values (for example, the beforeColor and afterColon options in the key-spacing rule).
    • In the future, rule docs might display a partial toc for these sub-headings under Options. Or your suggestion in the following point. Or both.
  4. Yes, we are still converging on patterns to describe options.
    • Links from options to subheadings for example code sounds helpful. Because links that contain code elements have been rare, we only recently changed the style to distinguish them from ordinary code elements! If we make this change, they become common, so we will need to review the style.
    • Interesting that we have been deleting the JSON configuration examples as we sweep through the rules and verify that the eslint comments in the example code are accurate. It seemed to get in the way. And was irritating when there was just a config with no example code. Let’s discuss this more.
  5. What do you mean by opening sections? In case you mean Rule Details and the introduction content that precedes it, that has been higher-hanging fruit. Here is a suggestion for us to discuss:
    • introduction section explains what is the software quality goal, why or to whom it matters.
    • Rule Details and Options explains how to use the rule to achieve the goal.
  6. Layout is definitely worth exploring, especially as a progressive enhancement that does not cause markup structure for core rule doc to become useless as pattern for third-party rule docs to follow.
    • What do you think about this quick-and-dirty experiment for example code?
      265 no-unused-expressions 1920 1080
  7. Folksonomy concept has great potential to improve “findability” of rules. Please explore and build a list of proposed tags as you work through the rule docs!

@originalfoo
Copy link
Contributor Author

2. For the pattern-matched comments above example code blocks, I feel we could have an even shorter variant, for example:

Invalid patterns for "as-needed":

// code sample

Valid patterns for "as-needed":

// code sample

I'm not sure how comprehensible the words "Invalid" and "Valid" are in other languages though?

Ultimately I'd like to keep boilerplate text to an absolute minimum, and also establish an "anti-yoda" pattern (specifically: keywords must appear at start of a sentence, and values at the end, with minimal "make it readable" words in the middle).

3. For partial TOC, I would suggest a horizontal list - at least initially, eg:

Jump to: Dependencies | Options | Examples

Longer term, I'm wondering if a sidebar with an always-visible vertical TOC would be better - it would make jumping round documents, regardless of where you currently are in the doc, much simpler.

Random thought: I would also like the page heading to become "sticky" so it's always visible at top of page regardless of vertical scrolling. I often have several rule pages open in tabs and being able to quickly see which rule a page relates to, without trying to read small tab text or having to scroll to top of page, will make life easier.

I'd like to suggest some alternate headings, but I still need to read through more docs to gather my thoughts then I'll post suggestion in #5446.

4. I'm working on a sample of how I think options section could be approached, in particular a summary of the syntax will be shown first, and then elaboration below. Hoping to have sample ready for preview later today.

Regarding JSON, I feel there are several merits to including it:

  • New users can quickly see what needs to go in their config file (I struggled with this at first)
  • ...and copy/paste it
  • It can show the full settings in legible form, ideally with the default options (make it clear what the starting point is for settings customisation)

5. Yes, I've been thinking along same lines.

A well structured intro can make the options significantly easier to describe because they can refer to the concepts described in the intro - and maybe even link to them. I'll put up an example of what I'm thinking later today.

BTW: I'd like to see an auto-generated "Dependencies" section directly above "Options" section. Example:

Dependencies

  • ESLint version X.Y.Z
  • es6 environment

By specifying things like environment up front, we don't need to clutter examples with the environment comments, thus keeping examples completely focussed on the rule being described by the page.

6. The side-by-side example is exactly what I was thinking - much, much, much better!

7. This will take a while to do, but a quick sample of tags below:

  • whitespace
  • parens
  • braces
  • operators
  • functions
  • loops
  • es6
  • node
  • brevity
  • consistency
  • ....

So there's different 'collections' of tags - language features, syntax elements, environments, project goals, etc. Simplistic namespacing in the config might be useful, eg: 'namespace:tag' - very easy to match using str.startsWith() and str.endsWith() due to colon, and easy to split for visualisation.

@pedrottimark
Copy link
Member

Example of pull request which illustrates the format of commit message for this work: #6291

Now we usually doing examples and options together.

Example of pull request for second pass through rule docs in which options was done as second pass after examples: #6270

You might be able to pick on this second pass for Best Practices where I left off.

@originalfoo
Copy link
Contributor Author

Mockup discussed in my previous comment: https://github.com/aubergine10/scrapbook/wiki

@platinumazure platinumazure added needs bikeshedding Minor details about this change need to be discussed question This issue asks a question about ESLint and removed triage An ESLint team member will look at this issue soon labels Jun 17, 2016
@pedrottimark
Copy link
Member

The thoughts in 2. at the beginning of #6444 (comment) do suggest a way to simplify and shorten example sentences.

Here are the current 8 wording prefixes matched by replacement rules:

Examples of **incorrect** code for this rule
Example of **incorrect** code for this rule
Examples of additional **incorrect** code for this rule
Example of additional **incorrect** code for this rule
Examples of **correct** code for this rule
Example of **correct** code for this rule
Examples of additional **correct** code for this rule
Example of additional **correct** code for this rule

@nzakas @ilyavolodin @scriptdaemon Do you think just these 2 could communicate the meaning?

**Incorrect** code for this rule
**Correct** code for this rule
  • Do you think “Examples of” is implied by the context?
  • Gets rid of singular versus plural.
  • Gets rid of “additional” for exception options, but contributors do not feel it is helpful distinction.
  • For this question, assume the rest of the sentence remains the same.
  • Moving the bold word adjacent to the corresponding icon seems like an improvement, see below:

6444 examples func-style

@aubergine10 Do the sentences in the picture satisfy the principle you suggested: keyword at beginning and value at end?

@nzakas nzakas added enhancement This change enhances an existing feature of ESLint documentation Relates to ESLint's documentation accepted There is consensus among the team that this change meets the criteria for inclusion and removed question This issue asks a question about ESLint labels Jun 17, 2016
@nzakas
Copy link
Member

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

@pedrottimark
Copy link
Member

@nzakas Thank you for reconstructing that part of the thinking process. What do you think about how clearly “additional” communicates for examples of exception options?

@aubergine10 Just sent you a direct message on gitter to see when we can chat.

Now I will let this simmer on low heat in my mind for a few days until I fix my big web site blunder 😳

@originalfoo
Copy link
Contributor Author

For text I suggest we stick with the current text for now and focus on getting all pages using the consistent text - once that's done we can bulk find and replace on the files in the docs folder to make any changes.

I'll be on gitter in an hour or so, bbl.

@nzakas
Copy link
Member

nzakas commented Jun 17, 2016

@pedrottimark I like "additional" as the modifier when showing how options affect the rule. 👍

@pedrottimark
Copy link
Member

Sorry that I worded some comments in confusing ways. Here is what I was trying to mean:

  • For the sake of contributors when they edit markdown content and commiters when they review it, we need to limit the amount of formatting magic to high-value enhancements that have an obvious cause-and-effect relationship. Also, if we enhance based on text content, the meaning is accessible.
    • Patterns should be common enough for people to find a similar rule or option.
    • Patterns should be robust enough for people to copy, paste, and edit for the context without breaking the enhancement.
  • Findability of core rules for a given quality goal or stylistic preference has improved with more consistent descriptions and the super site search. Some flexible set of tags for rules has potential, but on the other side of the coin, keeping Related Rules up to date with new rules seems hit-or-miss.

nzakas pushed a commit that referenced this issue Jun 22, 2016
1. Ensure each doc has "Examples" heading, and that each
    option-specific example pair also has a suitable heading.

2. Ensure text above examples is consistent as per #5446

This PR does not attempt to address issues other than
those stated above; such issues will be dealt with on
subsequent sweeps of the docs detailed in #6444..

Note: Skipped no-duplicate-imports due to #6455, will
come back to that one at later date.
nzakas pushed a commit that referenced this issue Jun 22, 2016
* Docs: Consistent example headings & text pt4 #5446

Final batch of es6 docs for this sweep!

1. Ensure each doc has "Examples" heading, and that each
option-specific example pair also has a suitable heading.

2. Ensure text above examples is consistent as per #5446

This PR does not attempt to address issues other than
those stated above; such issues will be dealt with on
subsequent sweeps of the docs detailed in #6444..

* Docs: Fixed lint errors in doc

docs/rules/sort-imports.md: 161: MD004 Unordered list style
docs/rules/sort-imports.md: 162: MD004 Unordered list style
docs/rules/sort-imports.md: 163: MD004 Unordered list style
docs/rules/sort-imports.md: 164: MD004 Unordered list style
docs/rules/sort-imports.md: 37: MD007 Unordered list indentation
docs/rules/sort-imports.md: 37: MD010 Hard tabs
docs/rules/sort-imports.md: 38: MD010 Hard tabs
docs/rules/sort-imports.md: 39: MD010 Hard tabs
docs/rules/sort-imports.md: 40: MD010 Hard tabs

* Docs: List indentation should be 4, not 2

FYI: I've requested enhanced error reporting for markdown linter - e.g.
to expose rule settings in error messages:
DavidAnson/markdownlint#23 (comment)
171
nzakas pushed a commit that referenced this issue Jun 22, 2016
* Docs: Consistent example headings & text pt3 #5446

Just a single doc in this batch due to variance in changes:

Headings were already present, however they were
over-complicated; I separated out the old (ES3/5) feature
from the heading and put it in a block quote to distinguish
it from the new (Reflect API) feature.

As per previous batches, ensured text above examples is
consistent as per #5446

This PR does not attempt to address issues other than
those stated above; such issues will be dealt with on
subsequent sweeps of the docs detailed in #6444.

* Docs: space around fenced code

* Docs: Remove blockquotes (refs #6492)
@nzakas
Copy link
Member

nzakas commented Oct 21, 2016

Is anything still happening with this issue?

@vitorbal
Copy link
Member

Nothing has happened for quite a while. @aubergine10 are you planning on doing any more changes to the docs or should we close this as complete?

@guerrero
Copy link
Contributor

There are still some rule pages that need to be updated in order to reflect the background color change for both incorrect and correct examples. Here is a list of some pages I've seen that need to be updated:

And it seems that there are some more. I can investigate which pages need these changes and make a PR if you're interested

@ilyavolodin
Copy link
Member

@guerrero We will always happy to review any PRs related to documentation improvements! If you have time to look - go for it!

@guerrero
Copy link
Contributor

Great @ilyavolodin! I've created a PR :)

nzakas pushed a commit that referenced this issue Nov 25, 2016
Some examples showed in the rules docs has outdated examples
without highlight so I've updated them in order to enable it.
I've also change the order in some examples and change some
minimum text to achieve this purpose
@kaicataldo
Copy link
Member

Closing this as @guerrero's changes have landed.

@eslint-deprecated eslint-deprecated bot locked and limited conversation to collaborators Feb 6, 2018
@eslint-deprecated eslint-deprecated bot added the archived due to age This issue has been archived; please open a new issue for any further discussion label Feb 6, 2018
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
accepted There is consensus among the team that this change meets the criteria for inclusion archived due to age This issue has been archived; please open a new issue for any further discussion documentation Relates to ESLint's documentation enhancement This change enhances an existing feature of ESLint needs bikeshedding Minor details about this change need to be discussed
Projects
None yet
Development

No branches or pull requests

10 participants