The Core Document Types Every Technical Writer Should Master
One of the fastest ways to level up as a technical writer is to stop thinking of "documentation" as a single thing. It is a family of distinct document types, each with a different purpose, structure, and reader mindset — and mixing them is the root cause of most confusing docs. A tutorial that turns into a reference, or a how-to guide padded with conceptual theory, fails because it is trying to do two jobs at once. Master the types individually and you gain a reliable toolkit for whatever documentation problem lands on your desk.
This field guide covers the core document types every professional writer should be able to produce on demand, with the purpose and shape of each. If you are just starting, our beginner's guide to technical writing gives the foundations, and our article on structuring technical content explains the information architecture these types plug into.
A Framework for Document Types
The clearest way to organise documentation is the Diátaxis framework, which sorts content along two axes — whether the reader is studying or working, and whether they need practical steps or theoretical knowledge. This yields four quadrants: tutorials (studying + practical), how-to guides (working + practical), explanation (studying + theoretical), and reference (working + theoretical). The insight is that each quadrant serves a genuinely different need, so a single page should rarely try to be more than one. Keeping them separate is liberating: you stop agonising over whether to include background in a procedure because the framework tells you background belongs in explanation, linked but not inline. Learn the four types and you have a decision tree for almost any documentation task.
Tutorials: Learning by Doing
A tutorial takes a beginner by the hand and walks them to a successful outcome, teaching through doing. Its goal is not to cover every option but to build confidence and a working mental model, so it should be a single, guaranteed-to-work happy path with no forks or edge cases. Every step must succeed for the reader, which means you test it obsessively on a clean environment. Explain just enough to keep them oriented, defer the why to linked explanation, and give them a visible win at the end. The classic beginner mistake is turning a tutorial into a reference dump; resist it. A great tutorial leaves the reader thinking "I can do this," which is the emotional foundation for everything they learn next.
How-To Guides: Solving Real Problems
Where a tutorial teaches, a how-to guide helps a competent reader accomplish a specific real-world task. It assumes some existing knowledge and jumps straight to the goal: "How to configure single sign-on," "How to migrate your database." How-to guides are goal-oriented and can acknowledge choices and variations because the reader has enough context to handle them, unlike a tutorial's rigid single path. Structure them as clear numbered steps with a stated prerequisite section up front and a way for the reader to verify success at the end. The most common failure is burying the actual procedure under conceptual preamble — the reader came to do something, so lead with the steps and link the theory for those who want it.
Reference: Reliable Lookup
Reference material is the dictionary of your documentation: comprehensive, consistent, and optimised for lookup rather than reading. Configuration options, command flags, function signatures, error codes, and parameter tables all live here. The cardinal virtues are accuracy and consistency — every entry follows the same structure, so once a reader learns the pattern they can scan any entry fast. Reference is not the place for tutorials or opinion; describe what is, precisely and neutrally. Because reference tends to be large and volatile, generate it from a source of truth wherever you can rather than hand-maintaining it, which keeps it accurate as the product changes and frees you from soul-destroying manual updates.
API Documentation
API documentation is a specialised, high-value blend of the core types, and demand for writers who can do it well is strong. A complete API doc set includes reference for every endpoint (parameters, request and response schemas, status codes, and error messages), a quickstart tutorial that gets a developer to their first successful call fast, how-to guides for common integration tasks, and clear authentication documentation — the number-one place developers get stuck. Modern API reference is typically generated from an OpenAPI specification, giving interactive, always-accurate docs, and tools like Postman let you provide runnable examples. Great API docs include real, copy-paste code samples in multiple languages, because a developer's first question is always "show me a working request."
Release Notes and Changelogs
Release notes are the most-read documentation many products have, and the most under-invested. They tell users what changed, why it matters, and what they need to do about it. Write them for the user, not the engineering team: "You can now export reports to CSV" beats "Merged PR #4821." Group changes into new features, improvements, fixes, and — critically — breaking changes, which deserve prominent placement and clear migration guidance. A changelog is the terse, chronological technical record; polished release notes are the user-facing narrative on top of it. To develop fluency across all these types on real projects, our Mastering Documentation Types course at Darlo Technical Writing includes worked examples of each, and comes with a downloadable API documentation template you can adapt for your own product. Explore the full catalogue at /courses. For collaborative standards on documentation types, the Write the Docs community is an excellent reference, and our guide to docs-as-code workflows shows how to publish them all.
The API Documentation Template
A complete Markdown template for documenting a REST API — endpoint reference sections, auth setup, request/response examples, error tables, and a quickstart — ready to fill in.
What is the Diátaxis framework?
It is a way of organising documentation into four types based on whether the reader is studying or working and needs practical steps or theory: tutorials, how-to guides, explanation, and reference. Keeping a page to one type is what makes it clear.
What is the difference between a tutorial and a how-to guide?
A tutorial teaches a beginner through a single, guaranteed happy path to build confidence. A how-to guide helps a competent reader accomplish a specific real-world task and can include choices and variations. Confusing the two is a common source of unclear docs.
What should complete API documentation include?
Endpoint reference with parameters and response schemas, a quickstart tutorial, how-to guides for common integrations, clear authentication docs, and real copy-paste code samples. Modern API reference is usually generated from an OpenAPI specification.