Phase 4: “Extend ESLint” of the Documentation Update Project Outline

[bpmutter]

Overview

This document outlines the changes for Phase 4: “Extend ESLint” of the Documentation Update Project.

Tasks

Ways to Extend ESLint page

New page with overview of various ways to extend ESLint.

Sections:

• Plugins
• Custom Rules
• Custom Parsers
• Custom Formatters
• Shareable Configurations

Overviews & Copy Edits on All Main Pages

On each of the following pages:

• Plugins
• Custom Rules
• Custom Formatters
• Custom Parsers
• Shareable Configurations

Create separate PRs to:

• add overview to page
  • At the top of pages explaining what an extension type is, and why you might want to use it.
    • For example, in the custom formatters documentation, explain why someone might want to create a custom formatter.
• copy edit

(Potentially) Create Separate Guided Tutorial Pages for All the Extension Types

I don't know if this is something we want to commit to maintaining. (Maybe it is though!) Worth discussion with core team.

• Guided tutorials for creating extensions
• Create a couple of “getting started” type tutorials for creating the most common extension types.
  • For example, a tutorial on making a plugin
  • These tutorials can provide opinionated guidance and promote best practices.

Investigate JSDoc for Node.js API

Probably won't be able to do full JSDoc-ing as part of this phase given the scope of that. But I would like to fully understand the feasibility of getting this done, and how it'd work with the rest of the ESLint documentation site.

tool like this could work - https://github.com/jsdoc2md/jsdoc-to-markdown/wiki
and here's an example of doing one docs file per class - https://github.com/jsdoc2md/jsdoc-to-markdown/wiki/How-to-create-one-output-file-per-class
might even be able to get full JSDoc-ing

Open Questions

TBD

Notable Not Doing

Tbd

[bpmutter]

moved to discussion from https://gist.github.com/bpmutter/8254ae79396ae7ea0a3e3d321befb4a3

[nzakas]

This looks like a good start! One thing that came to mind: right now the processors documentation is inside of the plugin documentation page. Should we maybe split that out into its own page to make it easier to find? Perhaps the plugin page just describes the different types of extensions a plugin can contain and then links out to the individual pages for rules, parsers, etc. (FWIW, parsers will be moving into plugins with the new config system.)

As far as guided tutorial pages: YES!!! I would love to do this. I think the hardest part is actually writing them and that maintaining them will be fairly straightforward. If you'd be up for it, I'd love to have you work on these.

[nzakas]

My fear is that such content would 1) get lost on the blog and 2) would never end up being updated. At least if we have stuff in the docs, it's front-and-center and we are more likely to remember to keep it up to date.

I would like to have some more task-based documentation rather than just reference-based, as I think we have reached the limits of the latter at this point.

[bpmutter]

ok, let's plan on doing guide/tutorial content. do you have any thoughts on:

• what the highest priority extension type(s) for this content would be?
• what content you'd like to see in these guides/tutorials

[nzakas]

I think the highest priority would be a guide to creating custom rules and distributing them in a plugin, as we recommend creating custom rules frequently.

Order of importance in my mind:

1. rules
2. shareable configs
3. parsers
4. processors

And I think I'd like to see a complete walkthrough from start to finish. So, for a rule, how do you determine which parts of the AST to look at? Once you do, how do you codify it in JavaScript? Once that's done, how do you write tests to verify the rule works? Once you do that, how do you package into a plugin?

[bpmutter]

Thanks that makes sense.

Before I start thinking about this, are you aware of any projects that have tutorials that you'd like to use as models for the work we do here?

[nzakas]

I've looked around but haven't found anything that would be relevant to this. I'll definitely keep looking around, though.