Most readers don't read documentation — they scan it for the one thing they need. Structure is what lets them find it.
Rules for scannable content
- Descriptive headings. "Export a project to PDF", not "Exporting". A reader should know from the heading whether the section is for them.
- Short paragraphs. Three to four sentences maximum; one idea each.
- Lists for items, tables for comparisons. If readers compare options across attributes, use a table.
- Front-load. The most important words go at the start of headings, sentences, and list items.
- One topic, one purpose. Don't mix a concept explanation, a procedure, and a reference table in one long page.
Use the right topic type
Click each card to see what it's for and how it's structured.
💡 Concept
Answers: "What is it and why does it matter?"
Structure: definition, how it works, when to use it, related tasks.
Structure: definition, how it works, when to use it, related tasks.
🛠 Task
Answers: "How do I do it?"
Structure: goal-based title, prerequisites, numbered steps, result.
Structure: goal-based title, prerequisites, numbered steps, result.
📖 Reference
Answers: "What exactly are the options?"
Structure: tables, parameters, values, limits — built for lookup.
Structure: tables, parameters, values, limits — built for lookup.
🧯 Troubleshooting
Answers: "Why isn't it working?"
Structure: symptom, cause, solution — one problem per section.
Structure: symptom, cause, solution — one problem per section.
Try it: fix these headings
"Miscellaneous"
✅ Split it up. A "miscellaneous" section means content without a home — give each item a heading that names what it helps the reader do.
"Settings"
✅ "Configure email notifications" — name the goal, not the screen.
"Important information about the process of user account deletion"
✅ "Delete a user account" — front-loaded, short, and task-based.
➡ Next: Write procedures that work