Why teams document at all
Documentation exists to move knowledge from one head to another across time. A new colleague needs it to get started, a tired colleague needs it at two in the morning, and the author needs it six months later when the details have faded. If a document does not serve one of those readers, it is probably not worth the effort of writing it or the effort of maintaining it.
This is general information, not a prescription. Teams differ in size, industry and regulation, and some fields require specific records. Where rules apply to your work, follow the standards and professionals that apply to you.
Decide what to document
No team can document everything, and a team that tries usually ends up with a large pile of pages that nobody trusts. A more workable approach is to ask a few questions about each candidate topic.
- Will someone else need this, or will I need it again after a long gap?
- Is it hard to rediscover by reading the code, the drawings or the system itself?
- Does it change slowly enough that a document will stay true for a reasonable time?
- Would a mistake here be costly?
Things that tend to pass these questions include how to set up a working environment, how the parts of the system fit together, the reasons behind major choices, how to perform routine and risky operations, and what the agreed interfaces and limits are. Things that often fail them include play-by-play descriptions of code that is already readable, and details that change every week.
Documentation also has different readers. A newcomer wants orientation, a maintainer wants reference detail, and an operator wants a checklist they can follow under pressure. Mixing these in one long page serves none of them well. Naming the reader before writing is a simple habit that improves most documents.
Common kinds of documents
Most teams end up with a handful of recurring types, even if they call them different names.
- Orientation material, such as a project overview and a README that tells a newcomer what the work is and how to run it.
- Design and decision records, which capture why something was built the way it was and what alternatives were considered.
- Specifications and requirements, which say what the system must do. The practice of writing requirements and keeping technical specifications readable is its own subject.
- Procedures and runbooks, which give step-by-step instructions for tasks that must be done the same way each time.
- Diagrams, which show structure and flow more quickly than prose can.
- Reference material, such as interface descriptions, parameter tables and glossaries.
- Notes and records of work done, such as test results and meeting outcomes.
Each type has different lifetimes. A decision record is meant to stay as a historical snapshot, whereas a procedure must be changed whenever the process changes. Treating them differently makes maintenance much easier.
Decide where it lives
A document that cannot be found might as well not exist. The most useful rule is to keep documentation as close as practical to the thing it describes, and to keep the number of places small.
Material about code often lives well in the same repository, because it can be changed in the same change as the code and reviewed with it. This fits naturally with version control, since the history of a document then comes for free. Longer-lived or cross-team material, such as onboarding guides and process descriptions, often suits a shared wiki or document space. Drawings and binary files may need their own storage with a clear revision scheme.
Whichever you choose, a few conventions help:
- Agree on one home for each kind of document and write that agreement down.
- Use predictable names and a simple folder or page structure.
- Make search work, and put a short index page at the entrance.
- Avoid copying content between places. Link to a single source instead, so there is only one version to correct.
Remote and distributed teams tend to depend on this even more, since nobody can lean over and ask. The wider topic of remote engineering tools often comes down to how reliably people can find and trust shared written material.
Decide who keeps it current
Documents decay for a simple reason: nobody is responsible for them. Assigning ownership is the most effective single measure a team can take.
- Give every significant document a named owner, which can be a person or a role rather than a whole team.
- Record a last-reviewed date on the page, so readers can judge its age.
- Make updating documents part of finishing work. A change is not done if it makes an existing procedure or diagram wrong.
- Include documentation in review. When colleagues check a change, they can also check whether the related pages still agree with it.
- Allow readers to flag problems easily, and respond when they do.
Reviews do not need to be heavy. A short, regular pass over the most-used documents, perhaps when a project reaches a milestone, is usually more realistic than a large annual clean-up that never happens. When a document is no longer useful, retire it clearly rather than leaving it to mislead people.
Keep documents short and usable
Good documentation is usually brief, specific and written for a particular task. A few habits help.
- Lead with the point. Say what the document is for and who it is for in the first lines.
- Use headings and short paragraphs so readers can scan.
- Prefer concrete examples over general statements.
- State assumptions and known limits plainly, including what the document does not cover.
- Write in plain words. Clear language is a kindness to colleagues whose first language differs from yours, and to your own future self.
Starting small
A team with little documentation does not need a programme. A sensible starting point is to pick the three or four situations that cause the most repeated questions or the most avoidable mistakes, write a short document for each, assign owners, and agree where they live. Add more only when a real need appears. Watching which questions are asked repeatedly in chat or in meetings is often the best guide to what is missing.
Over time, the aim is a small, trusted body of material rather than a large, doubted one. People use documents they have found accurate before, and stop using ones that have let them down. Protecting that trust, by keeping documents few, owned and current, is the heart of good documentation practice.