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
Comments
@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. |
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! |
@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 |
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.
|
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. |
Aside from contribution complexity, are there other factors which mandate the use of markdown? |
That's the most common language for OSS documentation, as far as I know. Also built-in Github support for displaying it. |
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. |
@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…?
|
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).
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.
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.
Regarding JSON, I feel there are several merits to including it:
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:
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.
So there's different 'collections' of tags - language features, syntax elements, environments, project goals, etc. Simplistic namespacing in the config might be useful, eg: |
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. |
Mockup discussed in my previous comment: https://github.com/aubergine10/scrapbook/wiki |
The thoughts in Here are the current 8 wording prefixes matched by replacement rules:
@nzakas @ilyavolodin @scriptdaemon Do you think just these 2 could communicate the meaning?
@aubergine10 Do the sentences in the picture satisfy the principle you suggested: keyword at beginning and value at end? |
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). |
@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 😳 |
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. |
@pedrottimark I like "additional" as the modifier when showing how options affect the rule. 👍 |
Sorry that I worded some comments in confusing ways. Here is what I was trying to mean:
|
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.
* 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
* 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)
Is anything still happening with this issue? |
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? |
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 |
@guerrero We will always happy to review any PRs related to documentation improvements! If you have time to look - go for it! |
Great @ilyavolodin! I've created a PR :) |
Closing this as @guerrero's changes have landed. |
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:
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:
.eslintrc
syntax (facilitate easy copy and paste)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?
The text was updated successfully, but these errors were encountered: