Most technical documentation is written for the author, not the reader. After producing 50+ technical articles and documentation sets, here are the patterns that consistently produce docs developers actually reference.
The Inverted Pyramid
Start with the answer, then explain. Developers scan documentation — they don't read it linearly. Put the code example first, then the explanation. Show the happy path before edge cases.
The Four Types of Documentation
Divio's documentation framework nails it: tutorials (learning-oriented), how-to guides (task-oriented), reference (information-oriented), and explanation (understanding-oriented). Most projects only have reference docs. Adding even basic how-to guides dramatically improves developer experience.
Writing Code Examples That Work
Every code example should be runnable. Copy-paste should work. Include imports. Show the output. If there are prerequisites, list them explicitly. Nothing destroys trust faster than a code example that doesn't compile.
Structure for Scannability
Use descriptive headings (not "Introduction" — say what the section actually covers). Keep paragraphs to 3-4 sentences. Use code blocks liberally. Add a TL;DR at the top for long documents.
The Maintenance Problem
Documentation rots faster than code. Link your docs to your CI pipeline. Use documentation linters. Assign ownership. Treat docs like code: review them, test them, version them.