This note builds on Divio's Grand Unified Theory of Documentation
- Tutorials: Learning-Oriented. Study + Practice
- How-To Guides: Problem-Oriented. Work + Practice
- Explanation: Understanding-Oriented. Study + Theory
- Reference: Information-Oriented. Work + Theory
I want to add one aspect to this, which is the opening hook. The subtitle of the project, a sentence of two that hooks you in, makes you feel good, etc. This, then, is my ideal documentation layout (e.g., for a README.md)
- Hook
- Table of Contents
- Explanation
- Tutorials
- How-To Guides
- Reference
Documentation as Ideation
PRFAQ is a strategy popularized by Amazon as a way to discuss product ideas before they exist (see ideation). I am inspired by this fake PRFAQ idea, and wonder if you can treat a README in a similar vein as a PRFAQ. That is, write the complete README before you write anything else. Write the explanation, reference, and how-to guide in the least. If you still like it by the end of it. Build it.