Documentation

Douglas Pereira

Write the path a beginner takes

• Install
• One real example
• The first error they will hit

Reference is not a tutorial

• You need both
• Tutorials have a plot
• Reference has a shape you can scan

Keep it next to the code

• Docs that live in another building go stale
• A broken example is worse than no example
• CI should catch the snippet if you can

Search is a feature

• Headings are for humans and for grep
• Say the words people actually type
• If the answer is in Slack, it is not documented