Note: this is the original draft of the notes! They've been integrated into Denperidge-Redpencil/project.D
An attempt at boiling down the amazing 30min talk/documentation on how to write better documentation into something unobtrusive enough for people familiar with it to use as a checklist, but instructive enough for people unfamiliar with it to somewhat do the thing.
For each tutorial: write as if you're teaching a child how to cook.
Checklist:
- Holds the readers hand from start to finish
- Gives a sense of achievement
- Works for everyone, with minimal explanation
- Also teaches what you take for granted
For each how-to: write down how to achieve 1 specific thing as if it were a cooking recipe.
Checklist:
- Only 1 practical goal per how-to
- Minimal explanation
- Flexible: works for different but similar uses
For each reference: write as if you are writing an encyclopedia article.
Checklist:
- Structured like the codebase
- Doesn't explain common tasks (how-to guides)
- Doesn't explain basic concepts (tutorials)
- Fully describes the machinery
For each background material: write as if you're writing about the history and context of a subject.
Checklist:
- Explains design decisions
- Considers alternatives
- Helps the reader make sense of things