Different reader goals call for different document types, and recognizing which one to write is half the work. A tutorial is a guided learning experience that takes a beginner through a sequence to build the mental model. A how-to guide is a recipe aimed at an informed reader who already has the mental model and just needs a specific goal reached. Reference documentation exhaustively lists endpoints, parameters, fields, and error codes in a lookup-oriented format with little narrative, and the most important and most-frequently-used fields are ordered first so readers can find the answer faster. FAQs answer anticipated, generic questions and are not a substitute for proper how-tos on complex tasks, while troubleshooting sections diagnose specific symptoms with concrete next steps and are procedural rather than informational. A troubleshooting tree maps symptoms to actions without prose walls: if you see X, check Y; if Y is true, do Z; if not, check W. An error code reference lists every error the system can return, with a unique identifier, plain-language meaning, common causes, and remediation steps.
Operational writing has its own patterns. A runbook gives on-call responders exact steps to diagnose, mitigate, and resolve a specific production issue. A postmortem is a written record of an incident covering timeline, root cause, contributing factors, customer impact, and concrete action items to prevent recurrence, written in a blameless frame so attention stays on systems, signals, and decisions under uncertainty rather than on individual scapegoats. A design doc explains a proposed technical change with a problem statement, goals and non-goals, the chosen solution, alternatives considered, trade-offs, risks, rollout plan, and open questions. An RFC is broader, written for an engineering audience to debate direction, while a design doc is more concrete and aimed at reviewers who will approve implementation. An Architecture Decision Record, or ADR, captures one significant decision, the context, the choice, the consequences, and the alternatives rejected, signed by date and author; recording the rejected alternatives prevents the same debate from restarting whenever a new joiner questions the choice.
A README answers five questions fast: what this is, who it is for, how to install, how to run, and where to learn more, with anything else pushed into linked docs. A CHANGELOG entry is a per-version note that lists user-visible changes under Added, Changed, Fixed, Removed, and Security, so users can see what to expect on upgrade, and SemVer's MAJOR.MINOR.PATCH scheme interacts with docs by pinning references to a major version while guides target the latest minor. API documentation is the human- and machine-readable description of an API, including endpoints, request and response shapes, error codes, authentication, rate limits, and examples, often expressed in OpenAPI and rendered into interactive reference. Deprecation notices must state the removal version, explain the migration path, and link to the replacement, because telling users something is going away without telling them how to move creates churn and support tickets. Feature flag documentation should describe the flag, its default, and which audiences currently see the feature, while known-issue sections list active bugs or limitations with workarounds, affected versions, and a link to tracking. Edge cases, error conditions, limits, and boundary behaviors belong in reference or troubleshooting rather than in tutorials, because the happy path and the unhappy path both deserve coverage.