Operational documentation is the written memory of a technical team. It is the set of runbooks, architecture notes, access maps, and recovery procedures that let a new engineer understand a system without sitting next to the person who built it. For lean teams of two to fifteen engineers running cloud-native infrastructure on AWS, GCP, or bare metal, this documentation is not a nice-to-have. It is the difference between a clean handoff and a six-month archaeology project. The colleague who replaces you will not inherit your Slack history, your mental model of the network, or your muscle memory for the deploy script. They will inherit what you wrote down.
This article is about writing documentation for that colleague. It covers what to document, how to structure it, and how to keep it from rotting. It is written for teams without dedicated SRE coverage, where the person who fixes the database at 2 a.m. is also the person who writes the README. The goal is not a documentation platform migration or a new wiki taxonomy. The goal is a set of documents that survive a personnel change.
Why Documentation Fails on Lean Teams
Most documentation fails for the same reason most backups fail: nobody tests it until they need it. A runbook that worked in March may reference a load balancer that was decommissioned in June. An onboarding guide may point to a repository that was archived. A recovery procedure may assume a database version that was upgraded two releases ago. On a lean team, there is no documentation engineer whose job is to keep these pages current. The work falls to whoever notices the drift, and usually nobody notices until the next incident.
The failure pattern is predictable. A team writes documentation during a project kickoff, then stops updating it when the project ships. Six months later, a new engineer joins and finds a wiki full of stale diagrams and broken links. The engineer learns the system by asking questions in Slack, and those answers never make it back into the wiki. The documentation becomes a museum of past decisions, not a working reference.
The fix is not more documentation. It is less documentation, written closer to the work, with a clear owner and a clear expiration date. A document that is too long to read during an incident is not a runbook. A document that is too vague to follow without tribal knowledge is not a handoff. The documentation you write for the colleague who replaces you should be short enough to read in one sitting and specific enough to act on without asking for help.
What to Document First
Start with the documents that would cause the most damage if they were missing. For most lean teams, that means three things: the recovery checklist, the access map, and the architecture overview. These three documents cover the failure modes that hurt the most: data loss, lockout, and confusion about how the system fits together.
The Recovery Checklist
A recovery checklist is a step-by-step procedure for restoring a critical service after a failure. It should be written before the failure happens, not during it. The checklist should name the exact commands, the exact file paths, and the exact order of operations. It should not say “restore the database.” It should say “run pg_restore -d appdb /backups/appdb-2024-11-01.dump on the primary database host, then verify with SELECT count(*) FROM users;.”
We have written about this before in Write the Recovery Checklist Before You Need It. The core idea is that a recovery checklist is a testable artifact. You can run it against a staging environment and see if it works. You can time it and see how long a restore actually takes. You can hand it to a new engineer and see if they can follow it without asking questions. If they cannot, the checklist is not done.
For a lean team, the recovery checklist should cover at least three scenarios: database restore, DNS or certificate failure, and a full-region outage on AWS or GCP. Each scenario should have a named owner, a target recovery time, and a list of dependencies. The checklist should live in the same repository as the infrastructure code, not in a separate wiki. That way, a change to the infrastructure can be reviewed alongside the change to the recovery procedure.
The Access Map
An access map is a document that lists who can access what, and how. It covers AWS IAM roles, GCP service accounts, SSH keys, database credentials, and third-party services like monitoring dashboards or DNS providers. For a lean team, the access map is often scattered across password managers, Terraform state files, and the memories of the two people who set up the accounts. When one of those people leaves, the team discovers that nobody else can log into the production console.
The access map should answer three questions for every system: who has access, how do they authenticate, and what is the recovery path if the primary credential is lost. For AWS, that means documenting the root account email, the IAM users with administrative access, and the MFA devices attached to each. For GCP, it means documenting the organization admin, the project owners, and the service account keys. For bare metal, it means documenting the SSH keys in authorized_keys and the password for the BMC or IPMI interface.
The access map is not a security audit. It is a handoff document. It should be written so that a new engineer can answer the question “how do I get into the production database?” without sending a Slack message to a former colleague. It should also be reviewed whenever someone leaves the team, because that is the moment when access hygiene breaks down. A departing engineer’s credentials should be rotated, not just noted in a spreadsheet.
The Architecture Overview
The architecture overview is a one-page description of how the system fits together. It should name the major components, the data flows between them, and the failure modes that matter. It should not be a complete diagram of every microservice. It should be the map that lets a new engineer find the right repository, the right dashboard, and the right person to ask.
A useful architecture overview includes: the list of services and what they do, the list of data stores and what they contain, the list of external dependencies and what happens when they fail, and the list of environments and how they differ. It should also include the names of the people who know each area best, because on a lean team, the architecture is still partly in people’s heads. The document is a pointer to that knowledge, not a replacement for it.
How to Write Documentation That Survives
The format of the documentation matters as much as the content. A document that is hard to update will not be updated. A document that is hard to find will not be read. A document that is hard to test will not be trusted. The following practices are based on what works for lean teams, not on what documentation vendors recommend.
Write in the Repository, Not the Wiki
Documentation that lives next to the code gets reviewed with the code. A pull request that changes a Terraform module should also update the runbook that describes how to deploy that module. A pull request that adds a new service should also add a section to the architecture overview. This is not a new idea. It is the same principle that makes infrastructure-as-code work: the source of truth is the repository, and everything else is derived from it.
For a lean team, the repository is the natural home for operational documentation. It is already versioned, already reviewed, and already searchable. A Markdown file in a docs/ directory is easier to update than a wiki page behind a separate login. It also survives a wiki migration, because it is just a file in Git.
Use Checklists, Not Essays
A runbook that reads like an essay is hard to follow during an incident. The person reading it is stressed, tired, and probably on a video call with three other people. They need a list of steps, not a paragraph of context. Write the steps as a numbered list. Put the commands in code blocks. Put the expected output next to the command. If a step has a prerequisite, say so at the top.
For example, a database restore runbook should look like this:
- Log in to the bastion host:
ssh bastion.prod.example.com - Find the latest backup:
ls -la /backups/appdb/ | tail -5 - Restore the backup:
pg_restore -d appdb /backups/appdb/appdb-2024-11-01.dump - Verify the restore:
psql -d appdb -c "SELECT count(*) FROM users;" - Notify the on-call channel that the restore is complete.
That is a checklist. It is short, specific, and testable. A new engineer can follow it without asking what “restore the database” means.
Date Every Document
A document without a date is a document that cannot be trusted. The reader does not know if it was written last week or three years ago. Add a “Last reviewed” line at the top of every operational document. When you review the document, update the date. If you have not reviewed it in six months, mark it as stale. A stale document is worse than no document, because it gives false confidence.
For a lean team, a simple convention works: every operational document gets a Last reviewed: YYYY-MM-DD line. During a quarterly review, the team checks the dates and updates or archives anything older than six months. This is not a heavy process. It is a five-minute check that prevents the wiki from becoming a museum.
What the Colleague Who Replaces You Actually Needs
When you leave a team, the person who replaces you does not need a complete history of every decision you made. They need enough context to operate the system safely. That means they need to know what is critical, what is fragile, and what is safe to ignore. The following sections describe what that looks like in practice.
The Critical Path
Every system has a critical path: the set of services and data stores that must be up for the product to work. For a typical web application, that might be the load balancer, the application servers, the primary database, and the DNS provider. For a data pipeline, it might be the ingestion service, the message queue, and the warehouse. The documentation should name the critical path explicitly, so that a new engineer knows where to focus during an incident.
The critical path should also include the dependencies that are easy to forget: the TLS certificates that expire, the IAM roles that are assumed by the deploy pipeline, the third-party API that the login flow depends on. These are the things that break at the worst possible time, and they are often not documented because they are “obvious” to the people who set them up.
The Known Failure Modes
Every system has failure modes that the team has already seen. The database ran out of disk space. The certificate expired. The autoscaling group hit its maximum size. The DNS provider had an outage. These failure modes are valuable documentation, because they tell the new engineer what to expect. They also tell the new engineer what has already been fixed, so they do not waste time re-diagnosing a known problem.
Write down the failure modes as a list. For each one, include the symptom, the cause, the fix, and the date it last happened. This is not a postmortem. It is a field guide. It should be short enough to scan during an incident and specific enough to act on.
The Safe-to-Ignore List
Not everything in a system is critical. Some services are experimental. Some alerts are noisy. Some dashboards are abandoned. A new engineer who does not know this will waste time investigating things that do not matter. The documentation should include a short list of things that are safe to ignore, with a one-line reason for each. This is the opposite of the critical path, and it is just as useful.
For example: “The staging-worker service is a prototype and can be down for days without impact.” Or: “The high-latency alert on the analytics dashboard is known to be noisy and is not actionable.” These notes save the new engineer from chasing ghosts.
Documentation as a Habit, Not a Project
The biggest mistake lean teams make is treating documentation as a project with a start and an end. They schedule a “documentation week,” write a bunch of pages, and then go back to shipping features. Six months later, the pages are stale and the team is back where it started. Documentation is not a project. It is a habit.
The habit is simple: every time you change a system, update the document that describes it. Every time you fix an incident, add the failure mode to the field guide. Every time you onboard a new engineer, note the questions they asked and add the answers to the onboarding guide. This is not a heavy process. It is a few minutes of writing per change, and it compounds over time.
For a lean team, the habit can be enforced with a simple rule: no pull request that changes infrastructure is merged without a corresponding change to the runbook. This rule is easy to check in review and it keeps the documentation tied to the code. It also means that the documentation is always as current as the last deploy, which is the best you can hope for on a team without a dedicated writer.
What to Do When You Are the One Leaving
If you are the one leaving, you have a unique opportunity: you know what you know, and you know what the next person will not know. Use that knowledge to write the handoff document you wish you had received. Do not try to write everything. Write the ten things that would have saved you the most time in your first month. That is the document your replacement needs.
Start with the access map. Make sure the next person can log into everything without your credentials. Then write the recovery checklist for the one system that scares you the most. Then write the architecture overview, with the critical path and the known failure modes. Then stop. Anything more is probably padding.
The handoff document should be reviewed by someone who is staying. That person should try to follow the recovery checklist without your help. If they cannot, the document is not done. This is the same principle as a fire drill: you do not know if the procedure works until you test it.
FAQ
How often should operational documentation be reviewed?
Every six months is a reasonable cadence for a lean team. The review does not need to be a formal meeting. It can be a checklist item in a quarterly planning session: open the docs/ directory, check the Last reviewed dates, and update or archive anything older than six months. The goal is to catch drift before it causes an incident, not to maintain a perfect library.
What is the difference between a runbook and a playbook?
A runbook is a step-by-step procedure for a specific task, like restoring a database or rotating a certificate. A playbook is a higher-level response plan for a class of incidents, like a database outage or a security breach. On a lean team, the two terms are often used interchangeably, but the distinction matters: a runbook should be specific enough to follow without thinking, while a playbook should be flexible enough to adapt to a situation that does not match the script.
Should documentation live in the code repository or in a separate wiki?
For operational documentation, the code repository is usually the better choice. It keeps the documentation versioned, reviewed, and tied to the code it describes. A separate wiki is useful for cross-team or company-wide information, but it tends to drift because it is not part of the pull request workflow. If you must use a wiki, link to it from the repository and treat the repository as the source of truth.
What should I do if I inherit a system with no documentation?
Start by writing the access map. You cannot document what you cannot access. Then write the recovery checklist for the most critical system, even if you have to reverse-engineer it from the infrastructure code. Then write the architecture overview as you learn it. Do not try to document everything at once. Document the things that would hurt the most if they failed, and add to the set over time.
The Next Step
This article is part of a series on operational resilience for lean technical teams. The next logical step is to write the recovery checklist for your most critical system, following the pattern in Write the Recovery Checklist Before You Need It. If you have a question about what to document first, or a story about a handoff that went wrong, send it to the Gray Haven Lab. The best documentation is written by people who have felt the pain of its absence.