Documentation

[ajafff]

• complete user facing documentation:
  • using local rules (rules maintained as part of the linted project)
  • using rules packages
  • using shareable configs
  • creating and publishing shareable configs (does that really need to be documented?)
  • processors
  • aliases
  • excludes
  • settings (currently not used)
  • usage with ts-node and uncompiled rules/formatters/processors
• developer facing documentation
  • writing custom rules
    • best practices
  • writing formatters
  • writing processors
  • how to use the library API
    • how to set up DI
    • which services are available
• rule documentation
  • each rule on its own page
  • description, rationale, metadata (requires type information, fixable, deprecation, ...)
  • with config examples
  • with good and bad code examples
  • Further Reading
  • Related Rules
  • History
    • Added in vX.Y.Z
    • Changes per version
  • add hover text for icons
  • create template for rule docs and mention it in the contributing docs
• overall
  • use github pages from a gh-pages branch
  • use docsify?
  • use a spellchecker (spellchecker-cli?)
  • paste our logo everywhere

[ajafff]

I'm currently working o enhanced rule documentation. Every rule is documented on a separate page with a detailed description, rationale and examples.
The rules that are already done have a link on the overview page: https://github.com/fimbullinter/wotan/blob/master/packages/mimir/README.md#rules

@aervin as you are the one who introduced code examples in TSLint, would you mind looking over the docs and give some feedback?

[aervin]

Nothing strikes me as "missing" after the addition of these updates you're working on. This repo has excellent documentation in general. Can't complain.

Some maybes:

• Move the 🔍, 🔧 etc icons into their own column to the left of the rule names in the overview page, and provide a legend of sorts above the list of rules to explain what these icons mean.
  • The detailed docs page for each rule should have these same indicators.
• Duplication of the Difference to TSLint rule / Why you should use it info in the detailed docs pages wouldn't be a bad thing IMO.
• Provide a template for the detailed rule documentation somewhere. Don't give contributors an excuse NOT to maintain the doc setup you've worked so hard to implement.
• Personally, I make much use of the Further reading portions of the ESLint docs. Linters are terrific learning tools (in my experience), and a rule author's curated list of articles would be very helpful to people like me.

[aervin]

Some 🎉 s:

• The version of wotan when the rule was introduced
• The version of wotan when the rule's source was last changed
• Rule-specific changelog on the detailed docs page, including version number

[ajafff]

This is some pretty good feedback. Thanks @aervin.
I added these suggestions to the ToDo list above. Some of them can probably be automated, e.g. per rule changelog.

[aervin]

@ajafff Thanks. If there's anything specific you'd like help on from that list, maybe open an issue? Otherwise, keep fighting the good fight. 👍