Technical Documentation: What to Write and How to Keep It Current

Technical documentation is the written explanation of how a system works and how to use, run and change it: the README, tutorials and how-to guides, reference and API docs, runbooks, architecture decision records and onboarding notes. A small team does not need all of it. It needs the few documents people keep asking about, each written for one kind of reader need, kept in the repository next to the code, and changed in the same pull request as the code it describes. It now has a second audience as well: the AI coding agents that read your repository before they touch it.

Technical documentation, software documentation, technical writing

The three phrases overlap. Technical writing is the craft: explaining something complicated plainly for a specific reader. Technical documentation is what that craft produces for a product or system. Software documentation is the slice of it about code: how to install it, call it, deploy it, fix it and extend it. This page is about the last one, for teams where the people writing the docs are usually the people writing the code.

The four kinds of documentation, by reader need

The most useful way to sort docs is by what the reader is trying to do. Diátaxis↗ (opens in a new tab), a framework by Daniele Procida, names four needs and four matching forms, and asks two questions of every page: does it inform action or understanding, and does it serve someone learning or someone already at work?

• Tutorials: action, for learning. A lesson that takes a newcomer by the hand through something that works, such as a first local build.
• How-to guides: action, for work. Directions to a real goal for someone already competent, such as rotating an API key.
• Reference: understanding, for work. Dry, complete description of the machinery: configuration options, CLI flags, endpoints, error codes.
• Explanation: understanding, for learning. Why the system is the way it is: the architecture, the tradeoffs, the history.

Most bad docs are two of these mixed together. A setup tutorial that stops to explain the design history loses the beginner; a reference page padded with advice is slow to scan. Keep each page to one kind and link between them.

The documents a software team actually needs

• README: the front door. What the project is, how to install and run it, where the other docs are. Keep it short and link out; it is the one page allowed to touch every kind briefly.
• Onboarding tutorial: day one for a new developer, from clone to a running app to a first small change. An onboarding checklist covers the people side.
• How-to guides: one per recurring task, such as adding a migration, cutting a release or adding a feature flag.
• Reference and API docs: every endpoint, parameter, config key and error. Generate what you can from the source of truth, such as an OpenAPI file or the code’s own types, so it cannot drift from the code.
• Runbooks: how-to guides for operations, written so anyone on call can follow them at 3 a.m. The runbook template has the six sections.
• Architecture decision records: one short explanation per significant decision, never edited, only superseded. Start from the ADR template.
• Design docs: the proposal before a larger change. See the technical design document template.
• Changelog and release notes: what changed, for users. See how to write a changelog.

Procedures outside the code, such as refunds, vendor onboarding or month-end close, belong in a standard operating procedure; the SOP template covers those.

A starter layout you can copy

README.md                  what, install, run, where the docs are
AGENTS.md                  commands and rules for AI coding agents
CLAUDE.md                  Claude Code only; can import AGENTS.md
CHANGELOG.md
docs/
  tutorials/first-build.md
  how-to/add-a-migration.md
  how-to/cut-a-release.md
  reference/config.md
  reference/api/           generated from openapi.yaml
  explanation/architecture.md
  adr/0001-use-postgres.md
  runbooks/stuck-job-queue.md

Folders named after the four kinds make the rule visible: a writer who cannot decide which folder a page belongs in is usually writing two pages.

How to write it: a short style guide

You do not need to invent a house style. The highlights of Google’s developer documentation style guide↗ (opens in a new tab) cover most of what matters for a small team:

• Write to “you,” in the active voice, so it is clear who does what.
• Put the condition before the instruction: “If the build fails, run the clean script,” not the other way around.
• Use numbered lists for steps that happen in order, and bullets for everything else.
• Put code, commands, file names and flags in code font, and UI labels in bold.
• Use sentence case for titles and headings.

Add two of your own. Every how-to guide and runbook starts with what the reader needs before step one. And every command in the docs is one you ran, from the directory the reader will be in.

Docs as code

Write the Docs defines docs as code↗ (opens in a new tab) as writing documentation with the same tools as code: issue trackers, version control, plain-text markup such as Markdown, code review and automated tests. For a small team that means four concrete habits:

1. Docs live in the repository, in Markdown, next to what they describe.
2. A change that alters behavior updates the docs in the same pull request, and review checks it.
3. CI checks what a machine can: broken links, a generated reference that is out of date, code samples that no longer run.
4. Documentation bugs are filed like any other bug, with the page and the wrong line.

The second habit does most of the work. Put “docs updated or not needed” in your definition of done and the docs stay about as current as the code.

Keeping technical documentation current

Docs go stale in predictable ways, and each has a cheap fix. Google’s guidance on timeless documentation↗ (opens in a new tab) warns against words that anchor a page to a moment, such as “currently,” “new,” “now,” “soon” and “latest.” Where a date matters, write the date or the version instead.

• Give every page an owner, by role rather than by name, so it survives people leaving.
• Delete what is wrong. A stale page is worse than a missing one, because people half trust it.
• Generate reference from code wherever you can, and write by hand only what cannot be generated.
• Review the top ten pages every quarter: the README, onboarding, the runbooks people actually opened.
• When someone asks a question in chat that the docs should have answered, the fix is a docs task, not a chat reply.

Documentation for AI agents

Coding agents read your repository before they change it, and they read a few files first. The AGENTS.md format↗ (opens in a new tab) describes itself as “a README for agents”: a predictable place for the exact build and test commands, conventions and no-go areas that would clutter a README for people. Claude Code reads its own CLAUDE.md, and reads AGENTS.md too when no CLAUDE.md is in the way. What belongs in each file is covered in AGENTS.md vs README.md vs skills.

For a public product or API there is also llms.txt↗ (opens in a new tab), a proposal by Jeremy Howard rather than a formal standard: a Markdown file at /llms.txt with an H1 naming the project (the only required part), a short blockquote summary, and H2 sections listing links to the pages an agent should read, ideally with plain Markdown versions of those pages.

Three rules keep agent docs useful. Keep them short, because they are loaded into every session. Point to your docs rather than copying them, because copies drift. And document what a model cannot know: every model has a knowledge cutoff, covered in Claude models explained, so your newest APIs and conventions exist for it only if they are written down.

Where fenbs fits

fenbs is not a documentation tool; it has no wiki or pages. It is where the work on your docs is tracked, and where assistants find what is not in the code. A wrong page is a bug and a missing how-to guide is an enhancement, each with a ref such as BUG-112 that you can quote in the pull request. Facts an assistant worked out go in AI context, which every connected assistant reads, and a person’s standing instruction, such as “update the docs in the same pull request,” goes on the Decisions and rules page as a rule. fenbs follows its own advice here: the guide people read in the app and the /llms.txt file assistants fetch are generated from one source, so they cannot disagree.