There's a whole piece about just api docs in general. We don't generate any for our packages locally, nor do we maintain any decent ones, and we have zero on our website.

TBH though for the vast, vast, vast majority of cases the lint guide is exactly what you need and nothing more. Everything else is automated in our tooling (esp if you use type-aware linting).

https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/parser#configuration

The only things you really need to do manually are if you want type-aware linting on non-standard extensions or if you use custom jsx (non react).

I understand most users would not need to read this, but it would still be useful to add, for clarity's sake—right now the parser feels mostly like a blackbox that just happens to work.

TBH, the lack of API docs in general seems more like a bug than a feature: maybe we'll have @typescript-eslint/typescript-estree's docs eventually? It doesn't have to be manually copied over, can just be generated dynamically at build time, or even configure Docusaurus to read it from its original place (we don't support it yet, but would be useful to add)

i do agree with createing documentation for this, there is already few projects that use ts-estree directly (eg. prettier)

Maybe we shove them in the Development section so end users won't want to read it?

To clarify - for typescript-estree speficially we have public API docs in the readme, and they are complete and cover the entire surface.

parser is a black box and shouldn't ever be used except via ESLint. So all the docs it needs is the parser options which get passed via ESLint config.

eslint-plugin is well documented.

eslint-plugin-tslint is adequately documented. I don't think we want to give it too much love. Ideally I'd love to see this deprecated at some point, given that tslint is well and truly deprecated (over 3 years) and there are good migration paths.

visitor-keys isn't intended to be consumed by anyone. types isn't either. They're publicly internal packages.
eslint-plugin-internal, shared-fixtures, website and website-eslint are all fully internal packages.

scope-manager has docs for the API surface, but assumes you know how to use eslint-scope. This could use improvrment and examples - there's a lot of power here people don't leverage (sadly) because they don't know how to use it. The core eslint docs also suck in this regard.

ast-spec I 100% want to generate docs for the ast - that was one of the motivations for splitting it out and structuring it like I have. There's a lot of work to do here though.

Which leaves utils and type-utils. These are the packages that I am referencing when I say "we have poorly maintained documententetion". My efforts there were slap-dash and lazy TBH lol.
These packages have the broadest applicability because they help others build plugins - and they are depended on by many!
Josh did a good job of adding the getting started guide, but they could benefit from auto-generated docs (using api-extractor maybe?).

The user base for our project can be broken down like so (with a rough guess of scale)

• plugin users - tens of millions - 99.999%+ of users
  • eslint-plugin
  • parser
• plugin authors - (tens of??) thousands
  • ast-spec
  • scope-manager
  • type-utils
  • utils
• parser consumers - hundreds, maybe low thousands
  • ast-spec
  • typescript-estree

In terms of how well we do...

• We do a really good job for plugin users. Need docs for weird/"advanced" setup.
• We do a so-so job for plugin authors. The getting started guide Josh wrote is good, but util docs are sorely missing.
• We do a good job for parser consumers, IMO. Maybe could use some examples?

Need docs for weird/"advanced" setup.

Yes, that's... basically the point here. I'm not so much a plugin author / parser consumer, so ast-spec / typescript-estree docs, albeit certainly interesting to me, are not too critical. However, the lack of parser docs has often left me a bit clueless.

With the general trend of migrating off GitHub for viewing docs, I think we should work towards making everything available on the website. They don't have to be under the same category as user-facing linting docs—not even listed in the same sidebar—but the presence of this makes our docs at least self-contained.

Just take parserOptions.project as one example. The first encounter tells me I can do project: ['./tsconfig.json']. Then in the monorepo guide I learned that I can do project: ['./tsconfig.eslint.json', './packages/*/tsconfig.json'],. But even further down, I learned I should have one root tsconfig including everything to avoid summoning too many programs. The docs are a bit all over the place, and I'm just rigidly following the steps here, without a solid higher-level view of what all these configurations imply (although with my familiarity with TS programmatic APIs I can take educated guesses).

On the other hand, we have very concrete documentation right there in the README, listing all nuances. Simply making this available on the website and having a link from the "Linting with Type Information" section would probably make me happy.

I'm going to tentatively mark this as accepting PRs with two caveats:

• For now, the docs should be within the Development section of the website
• Anything documented should be clearly useful for users - e.g. a parser option that some slice of end-users would need to configure

My hunch is that we'll have a few pieces of docs relevant to some users, such as the parser ones, but not too many.