markdown-docs

Topics in the source

• Markdown docs
• 1. Identify the reader and their moment
• 2. Front-load ruthlessly
• 3. Make every command actually runnable
• 4. Structure for scanning, not reading
• 5. Write what cannot be inferred
• 6. Fight rot deliberately
• Formatting that helps

Documentation is read by someone mid-task who is slightly annoyed. They do not read from the top; they scan for the part that matches their situation, take it, and leave. Every structural decision follows from that. The most common failure is not absence — it is documentation organised around the system's structure instead of the reader's task. A page-per-module reference is easy to generate and answers almost no real question. Different moments need different documents, and merging them serves none: | Moment | They need | Document | | --- | --- | --- | | "What is this, should I use it?" | Purpose, fit, constraints | README top section | | "Get me running" | The shortest working path | Quickstart | | "Teach me the concepts" | Mental model, why it works this way | Guide | | "What are the options for X?" | Complete, scannable facts | Reference | | "It's 3am and it's broken" | Symptom → action, no prose | Runbook | | "Why is it built this way?" | Context, alternatives, trade-offs | Decision record | Write one of these at a time. A quickstart that pauses to explain architecture loses the reader who wanted to be running in two minutes. Done when: you know which document you are writing

This is an excerpt. Refer to the complete source and its current requirements.