Technical Documentation Types: What Agile Software Teams Actually Need to Write

The most widely used answer is Diataxis, a framework by Daniele Procida that splits documentation into four types: tutorials, how-to guides, reference and explanation. It sorts documents by what the reader is trying to do rather than by subject or author. It is one influential model, not a ratified standard, and other sources answer with a different four.

This is for product managers and tech leads deciding what a delivery team should write. It covers the four types, the competing answers, the documents that survive contact with a real sprint, and the ones you can stop producing tomorrow without anyone noticing.

What are the 4 types of technical documentation?

Diataxis divides technical documentation into tutorials, how-to guides, reference and explanation. Daniele Procida developed it out of open-source documentation practice, and it has since been picked up widely by both open-source projects and internal engineering teams. It is popular because it is a diagnosis, not a filing system: it tells you why a page is unsatisfying to read.

Type	Reader’s question	Typical form	How it goes wrong
Tutorial	I am new, take me through it	A guided lesson with a guaranteed working result	Drifts into explaining options the beginner cannot use yet
How-to guide	Help me do this specific task	Numbered steps for someone who already knows the domain	Restarts from first principles every time
Reference	What are the parameters and return types	API docs, configuration options, schemas, error codes	Written as prose when it needs to be a lookup table
Explanation	Why is it built this way	Architecture notes, design rationale, trade-offs recorded	Never written, so the reasoning leaves with the author

The split Diataxis actually draws is between two axes: whether the reader is studying or working, and whether they need practical steps or theoretical understanding. A tutorial is study plus steps. A how-to is work plus steps. Reference is work plus understanding. Explanation is study plus understanding. That is why the model holds up better than most: it describes the reader’s situation, which is stable, rather than the document’s subject, which is not.

Search the same question elsewhere and you will be given a completely different four: user documentation, system documentation, API documentation and process documentation. That split is by subject and audience, and it is equally defensible. Neither is official. No standards body ever ratified a set of four, so if a page presents its list as the industry standard, it is guessing with confidence.

Both models are worth knowing for the same reason. When a document is annoying to read, it is usually because two types have been welded together: an API reference with a tutorial embedded in it, or a getting-started page that keeps stopping to explain the architecture. Splitting them is nearly always the fix.

Which technical documents does an agile team actually need?

The ones with a named reader and a specific day that reader opens them. Most technical documentation is written once, read never, and maintained by nobody, and the reason is almost always that it was produced to satisfy a process rather than a person.

The test worth applying is not which types exist. It is what breaks if this document does not exist. Ask that of every document your team currently produces and the list gets short quickly.

Document	Who opens it, and when	What breaks without it	Worth maintaining?
API reference	An engineer integrating against you, while writing the call	Integrations built on guesswork, then support tickets	Yes, and generate it from source where you can
Runbook	Whoever is on call, at three in the morning	Recovery depends on which person happens to be awake	Yes, edited immediately after any incident that used it
Decision record	Someone asking why on earth it works this way, months later	The decision gets relitigated, or quietly reversed by accident	Never edited, only superseded by a newer record
Technical spec or design doc	Reviewers, before the code is written	Design objections turn up as pull request comments	No, it expires when the work ships
Onboarding and environment setup	A new joiner in their first week	Every hire costs a senior engineer several days	Yes, and the newest joiner should be the one editing it
Test plan	The team agreeing what tested means for this release	Coverage arguments after release, in public	Per release, not permanently
Weekly written status for management	Nobody, in practice	Nothing measurable	No

That last row is not a joke. Status documents written for an audience who could get the same information from the board are the largest single category of documentation waste on most teams, and they are the hardest to stop because someone senior once asked for them.

Every document you keep is a standing liability. A stale one is worse than a missing one, because a missing document sends people to ask a human, while a wrong document sends them confidently in the wrong direction.

Decision records are the cheapest of these to write and the most expensive to reconstruct. The reasoning behind a choice is available for about a week after the meeting and then it is gone. Some teams handle that with a nominated scribe. Others use a tool such as Projan, which puts the clarifying questions to the team in Slack or Microsoft Teams and writes the agreed answers out as a document with the tasks attached. The mechanism matters far less than catching the reasoning while it is still in someone’s head, and what belongs in an architecture decision record covers the structure that keeps one alive.

What are the 5 types of documentation best suited for agile environments?

There is no canonical five. No agile framework defines a set, and lists claiming otherwise are usually describing whatever their author happens to write. The five below are the ones that consistently earn their place on a team shipping every week or two, offered as a working shortlist.

1. The requirement, in whatever form your team uses. A user story, a PRD, a well-written ticket. The document that states what is being built and how you will know it is finished. Form matters less than whether an engineer can act on it without a follow-up conversation.
2. The design document, for changes big enough to argue about. Not every ticket needs one. Anything touching a service boundary, a data model or a security control does. Keeping a technical spec short enough that people read it is most of the skill.
3. The interface contract. API reference, event schemas, published error codes. This is the documentation other people build against, which makes it the one where being wrong is most expensive. Generate it from the code or a schema file so it cannot drift.
4. Operational documentation. Runbooks, alert descriptions, deployment and rollback steps. Written for someone under pressure, so short numbered steps and exact commands, not narrative. A runbook has a structure worth following precisely because nobody wants to interpret prose during an outage.
5. The decision record. One short entry per significant decision: context, choice, alternatives rejected, date. Append-only. This is the document that stops a team spending a fortnight rediscovering why the obvious approach was rejected in 2024.

Note what is missing. No per-feature wiki page, no meeting notes filed as documentation, no process manual describing how the team works. Those are not banned, but none of them has a reader with a date, and they are the first things to rot.

Does agile mean you should not write documentation?

No. The Agile Manifesto puts working software over comprehensive documentation, and the sentence people leave out is the one saying that while there is value in the items on the right, the items on the left are valued more. It is a statement about priority when the two compete, not a permission slip.

The misreading is convenient, which is why it persists. Teams quote it to skip the documents they find boring while continuing to produce the ones they enjoy or the ones a manager checks. That is a preference, not a documentation philosophy.

What genuinely changes on an agile team is timing and proximity. You write less, later, and closer to the code. Three habits do most of the work:

• Write it when the reader appears, not before. A setup guide written before anyone has set the project up is fiction. Write it while pairing with the first person who tries.
• Keep documents in the repository. A page in the repo gets reviewed in the pull request that invalidates it. A page in a wiki gets found in eighteen months and believed.
• Prefer deletion to updating. If nobody can name the reader, delete it. Version control means nothing is really lost.

What is an RFC format?

An RFC (request for comments) is a written proposal circulated for review before a decision is made. Two quite different things share the name, and mixing them up causes confusion in engineering conversations.

The original meaning is the IETF document series. Those RFCs are numbered, published by the RFC Editor, and follow a set structure: an abstract, a status of this memo section, an introduction, the technical body, mandatory security considerations, any IANA considerations, and references. The important property is that a published RFC is never edited. Changing a standard means publishing a new RFC that updates or obsoletes the old one, which is why the numbers keep climbing. How public RFCs are written, published and enforced goes into that process properly.

The second meaning is internal. Many engineering teams call their design proposals RFCs, borrowing the name and none of the machinery. There is no fixed structure, but the ones that work tend to carry: a title and author, a status, the problem and its context, the proposal, the alternatives considered and why they were rejected, open questions, and the named reviewers whose agreement is needed.

The rule worth stealing from the IETF version is immutability. An internal RFC that is quietly edited after approval stops being a record of what was agreed and becomes a description of what someone later wished had been agreed. Supersede it instead, and leave the old one in place with a pointer.

Frequently asked questions

What is an example of an important RFC? RFC 2119 is the one most engineers meet without noticing. It defines what MUST, SHOULD and MAY mean in a specification, which is why those words appear in capitals. Others in the same league are RFC 791 and RFC 793, which specify IP and TCP, and the HTTP specifications that have been revised several times since RFC 2616.

What is the difference between user documentation and technical documentation? User documentation is written for the people using the product: help articles, guides, release notes. Technical documentation is written for the people building or running it: API references, architecture notes, runbooks. The same feature often needs both, written differently. One document trying to serve both audiences usually serves neither, because the two readers arrive with different questions.

Who owns technical documentation on an agile team? The team that owns the code owns its documentation. Naming a documentation champion works for about a month and then breaks, because the champion is not the person making the changes. Attach docs to the work instead. If a change alters an interface or an operational step, updating the document is part of that change rather than a follow-up ticket.

How do you stop documentation going stale? Reduce the number of documents first, because fewer pages get updated more reliably than many. Generate whatever can be generated from source. Keep the rest in the repository so edits show up in code review. Give anything that survives an owner and a last-reviewed date, and delete pages nobody has opened in a year rather than reviewing them.

Should documentation be part of the definition of done? Only where the requirement is specific. A blanket docs updated checkbox gets ticked without thought. A rule saying that a change to a public interface regenerates the reference, and a change to an operational procedure edits the runbook step, is checkable by the reviewer. Broad documentation clauses produce compliance rather than documents anyone reads.

The four types are a useful diagnostic and a poor plan. Knowing you have written a tutorial where a reference was needed is worth something; knowing which documents have a reader with a date in the diary is worth considerably more. Write those few properly, keep them next to the code, and be unsentimental about everything else.