Foundations / Explanation
Choose the right document type
Separate learning, task completion, lookup, and understanding.
Four reader needs
A tutorial guides a learner through a successful experience. A how-to guide helps a reader finish a defined task. Reference provides precise facts for lookup. Explanation builds understanding of concepts and tradeoffs. Diátaxis describes these four purposes; Divio offers a related introduction.
Apply the distinction
For an imaginary export feature, create a tutorial that produces a first sample export; a how-to for exporting a selected date range; a reference listing supported fields and formats; and an explanation of how export permissions work.
Make boundaries useful
Link from a task to reference details instead of interrupting every step with every possible parameter. Link to explanation when readers need the reason behind a choice. A page may connect several needs, but its main purpose should remain easy to recognize.
Review question
Ask what the reader should be able to do after the page. If the answer includes learning, troubleshooting, and looking up every field, divide the material and connect it with descriptive links.
Sources & further reading
Original guidance and examples by TechWriter, informed by these resources.