8 Software Documentation

Purpose and reader needs

Documentation is most useful when it answers a reader’s question at the point the reader needs the answer. Questions may concern how to complete a task, what an interface accepts, or why a system was designed in a particular way.

Organizing material around user needs helps distinguish tutorials, task-oriented guides, technical reference, and explanations. The purpose should guide both what a document contains and how it is organized.

Forms of technical documentation

Technical documentation serves people who use, develop, integrate, or operate a software system. Choose its form according to the reader’s goal; mixing different purposes can make information harder to find.

• Getting-started guides and tutorials help readers learn by following a working example.

• How-to guides explain how to accomplish a specific task, such as configuring a database connection.

• Reference documentation gives precise facts, such as configuration options, commands, types, and interface behavior.

• Explanations and design overviews clarify architecture, concepts, constraints, or trade-offs.

• Operational guides cover deployment, monitoring, recovery, and troubleshooting.

For example, step-by-step setup instructions belong in a how-to guide, while a complete list of configuration fields belongs in reference documentation.

Recording architecture decisions

An architecture decision record (ADR) captures one significant design decision and its reasoning. Together, ADRs form a decision history that helps future team members understand what was chosen, why it was chosen, and what trade-offs were involved.

A lightweight ADR commonly includes:

• Title: a short description of the decision.

• Status: a clear state, such as proposed, accepted, or superseded.

• Context: the relevant problem, constraints, and requirements.

• Decision: the selected option.

• Consequences: benefits, costs, risks, and follow-up work.

Keep records brief and focused on decisions that are costly, consequential, or difficult to reverse. If a decision changes, preserve the earlier record and create a new record explaining what superseded it. ADRs document the reasoning at the time; they do not replace current system documentation.

Decision context and consequences

For example, a team might choose to store uploaded files in object storage rather than in the application database. The context could include file size and scaling needs; the consequences could include simpler database backups as a benefit, alongside the need to manage storage permissions and cleanup.

This example illustrates why the decision record should capture context as well as consequences: a future reader needs to understand the circumstances and trade-offs behind the choice.

Making API contracts clear

API documentation is the contract between an API provider and its users. It should make clear how to call each operation and what to expect. Depending on the API, document:

• The endpoint or method, its purpose, parameters, and required fields.

• Authentication and authorization requirements.

• Request and response formats, with realistic examples.

• Possible errors and their meanings, including how a caller can respond.

• Limits, pagination, versioning, and compatibility expectations where relevant.

For a GET /items/{id} operation, specify how id is supplied, what a successful response contains, and what happens if the item does not exist or the caller lacks permission. Examples should agree with the actual contract and avoid secrets or sensitive data.

Using OpenAPI descriptions

For HTTP APIs, an OpenAPI description provides a standard, machine-readable interface definition that people and tools can use to understand a service. It can support rendered reference pages and automated checks.

An OpenAPI description does not, by itself, explain every concept or task an API user needs. Pair generated reference with focused tutorials and guides when appropriate.

Maintaining documentation as software changes

Documentation can become unreliable when software changes but its instructions and examples do not. Treat documentation as part of the product, and update it when related behavior, interfaces, or operating procedures change.

A docs-as-code approach can use familiar development practices, including issue tracking, version control, code review, and automated tests. Keeping documentation in version control can make it possible to review and track changes alongside code.

A practical maintenance process

A practical maintenance process combines review, automation, ownership, and attention to important pages:

1. Keep docs near the work when useful. Store documentation in version control so changes can be reviewed and tracked alongside code.

2. Review documentation changes with software changes. Include relevant updates in the same change request, or explicitly identify why no documentation change is needed.

3. Automate checks. Validate links, formatting, API descriptions, and runnable examples where feasible. Automation catches mechanical errors, but people still need to check accuracy and clarity.

4. Assign ownership. Make clear which team or role is responsible for important areas, especially operational instructions and public API guidance.

5. Revisit high-impact pages. After significant releases, check frequently used setup, troubleshooting, and integration guidance. Remove duplicate or obsolete instructions and make the current version easy to identify.

Good documentation is not necessarily exhaustive. It should be accurate enough for its purpose, easy to navigate, and maintained as the system evolves.

• Software documentation

• Tutorial