Documentation Update Project

[bpmutter]

This issue encapsulates the proposed work for updates to the ESLint documentation website, https://eslint.org/docs.

Phase 1: Get to know docs with smaller, well-defined tasks

Tasks:

• docs: Add configs from plugin usage for the new config system. #16310
• More documentation on conflicting fixes #13721
  • add as a section on https://eslint.org/docs/latest/developer-guide/working-with-rules
• Change Request: Better documentation for Scopes #16148
• Core Concepts documentation #16382. Page covering the core concepts of ESLint. rules, plugins, etc.

Phase 2: High-level information architecture update

Outline and implement an update to the ESLint documentation’s information architecture (IA). Refactor the documentation around tasks related to three core personas:

• The User: Someone who wants to use ESLint as it currently exists, including plugins.
• The Extender: Someone who wants to extend the functionality of ESLint by creating a plugin, custom formatter, custom parser, sharable configuration, etc.
• The Contributor: Someone who wants to add to the ESLint core project, whether submit a request or develop a a new rule.
• The Maintainer: Someone who wants to oversee management of the core ESLint project.

Tasks:

• Outline information architecture changes
• Formal RFP: docs!: Docs information architecture refactor rfcs#97
• docs: add redirects for docs IA update eslint.org#388
• docs: IA Update page URL move #16665
• docs: Update page titles, section landing pages, and side TOC #16720
• Change Request: Create new page for adding core rules #16648
• Change Request: docs: custom processor documentation #16761
• Change Request: Configure Parsers documentation #16762
• Change Request: Code of Conduct page #16763
• Change Request: Report Security vulnerabilities page #16764
• Change Request: Refactor 'Set up Development Environment' page #16775

Procedure to use with each of the page moves: IA Update Procedure

Phase 3: “Use ESLint in Your Project” documentation update

Add additional documentation on using ESLint for the user persona.

Tasks:

• Outline section changes
• Overviews & copy tweaks in user documentation pages #16473
• Docs: Getting Started Clean up & Expansion #16508
• Standardize CLI documentation #16475
• Formatters Page Clean Up & Expansion #16476
• Integrations Page Clean up & Expansion #16477
• Configuring documentation section cleanup #16478
• Standardize Rule Documentation #16474

Phase 4: “Extend ESLint” documentation update

Add additional documentation on using ESLint for the extender persona.

Tasks:

• Phase 4: “Extend ESLint” of the Documentation Update Project Outline #16736
• Investigate creating generated reference docs for Node.js API (perhaps with tool like JSDoc)
• Change Request: 'Ways to Extend ESLint' page #16810
• Change Request: Plugins page clean up and expansion #16811
• Change Request: Custom Rules clean up and expansion #16812
• Change Request: Custom Parsers clean up and expansion #16813
• Change Request: Custom Processors clean up and expansion #16814
• Change Request: Shareable Configs clean up and expansion #16815
• Change Request: Custom Formatters clean up & expansion #16885
• Change Request: Custom Rule tutorial #16940

Phase 5: “Maintain ESLint” documentation update

Add additional documentation on using ESLint for the maintainer persona.

Tasks:

• Docs Update Project Phase 5: Maintain ESLint #16905
• Change Request: Copy edits on the 'Maintain ESLint' section #16938
• Change Request: How ESLint is Maintained page #16941

Phase 6: "Integrate ESLint" documentation update

Add additional documentation on using ESLint for the integrator persona.

Tasks:

• Change Request: Integrations docs section #17133
• Change Request: Create guide to integrate with ESLint Node.js API #17134

Phase 7: "Contribute to ESLint" documentation update

• Outline section changes not taking action b/c of ESLint complete re-write which'll affect some of the contributing docs (Complete rewrite of ESLint #16557)

Phase 8: ESLint Flat Configs

• Change Request: .eslintrc -> eslint.config.js migration guide #17229

Miscellaneous

New issues that have come up throughout the documentation update project. Can be completed outside of the above phases.

• update section headings to use non-gerund forms #16578
• Docs: Better example for shared setting #16507
• Consistently use "an .eslint..." throughout the docs. spun off from this thread docs: add intro and edit ignoring files page #16510 (comment)
• docs: Title Case for all headings #16609
• Change Request: Give advice on when to use disable comments #16754

[bpmutter]

@nzakas looks like i cannot set the labels for the issue. could you remove the core label and add a documentation label, in addition to any others you think necessary?

[nzakas]

@bpmutter all set. 👍

[ollie-iterators]

The pull requests: eslint/eslint.org#388 and #16665 have been merged

[ollie-iterators]

Yay, Phase 2 is complete!!!

[ollie-iterators]

#16810 can be checked off now

[nzakas]

Very strange. That should happen automatically. Must be a bug on the GitHub side.

[ollie-iterators]

I just noticed Phase 5 is complete!!

[ollie-iterators]

I've noticed that there is more work being done on phases later than Phase 3. When is the work on standardizing rules documentation going to be done?