Grand Unified Theory of Documentation

Image of Author
June 26, 2022 (last updated October 24, 2022)

This note builds on Divio's Grand Unified Theory of Documentation

documentation graph

  1. Tutorials: Learning-Oriented. Study + Practice
  2. How-To Guides: Problem-Oriented. Work + Practice
  3. Explanation: Understanding-Oriented. Study + Theory
  4. 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)

  1. Hook
  2. Table of Contents
  3. Explanation
  4. Tutorials
  5. How-To Guides
  6. 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.