Technical Documentation: Decisions, Runbooks and Tested Handover

Choose documentation by the reader's task, then maintain useful ADRs and operational runbooks with ownership, access controls, validation and update triggers.

Write for the moment someone needs to act

An on-call engineer opens a queue-backlog alert. The linked document explains why the company adopted asynchronous processing, but does not identify the queue, the owning team or a safe way to distinguish stuck work from a slow dependency.

The explanation may be accurate. It is still the wrong document for that task.

Start by identifying the reader's decision: learn a workflow, perform an operation, look up a contract or understand a design choice. The Diátaxis framework distinguishes tutorials, how-to guides, reference and explanation around those different needs. You do not need four documents for every feature. You need a clear path from the reader's question to the appropriate evidence or action.

Documentation does not guarantee a particular onboarding time or incident duration. Its usefulness must be checked through the tasks it supports.

Choose a document and a source of truth

| Reader need | Useful document and boundary | |---|---| | Make a first local change | A tested tutorial with prerequisites, expected output and cleanup. Keep production access out of the learning path. | | Understand an architectural choice | An ADR describing context, decision, alternatives and consequences. It records rationale, not the current operational procedure. | | Respond to a known symptom | A runbook with scope, observations, authorized actions, stop conditions and escalation. | | Integrate with an API | Versioned reference plus examples of authentication, errors, retries and compatibility behavior. | | Find the system owner | A concise service overview linked from the repository and service catalog. Include dependencies and escalation routes. |

Code-adjacent documentation works well when it changes with the implementation and its audience can access the repository. A portal helps readers find cross-team material, but copying the same procedure into two places creates competing sources of truth.

Choose one authoritative version and link to it. If a portal renders repository content, preserve the source revision and publication status. If an incident can make the portal unavailable, provide an approved fallback with clear freshness and access expectations.

Generated API schemas reduce repetitive maintenance. They do not explain business intent, side effects or recovery from ambiguous outcomes unless those semantics are deliberately documented.

Worked ADR: retain failed export jobs for inspection

The following is a fictional example, not a decision taken for an Ampity client. Its purpose is to show a complete, reviewable record.

| ADR field | Example entry | |---|---| | Title and status | ADR-014: retain failed export jobs for operator inspection. Accepted within this illustrative design. | | Context | An export worker reads queued jobs and writes private report objects. Some failures come from malformed payloads; others come from temporary storage errors. Retrying all failures indefinitely makes the backlog difficult to diagnose. | | Decision | Distinguish retryable failures from invalid jobs. Retain exhausted or invalid jobs in a restricted inspection queue. Do not replay them automatically after a deployment. | | Alternatives | Drop failed jobs, retry without a bound, or require a human decision after bounded attempts. The design chooses the third option. | | Consequences | Operators gain an inspection path but now own triage, retention and authorized replay. Job status must remain visible to the requester without exposing report contents. | | Constraints | Replay must preserve the job's logical identity and deduplication behavior. Retention follows the approved data policy. A replay procedure is required before enabling operator replay. | | Owner and review trigger | Export-service team. Revisit when payload versions, storage behavior, retention requirements or replay semantics change. |

Michael Nygard's ADR guidance explains why context, status, decision and consequences belong together. Preserve the old record when a later decision supersedes it. Update current runbooks and link the replacement ADR rather than silently rewriting the history.

This ADR deliberately leaves retry counts and retention periods to the system's requirements. A copied number without a workload or policy basis would make the example less useful.

Worked runbook: export backlog stops draining

This example describes a hypothetical service. It has not been executed against a live environment. An actual team must replace the resource identifiers, access route and escalation contacts, then rehearse the procedure before relying on it.

Runbook: RB-EX-02, export backlog triage.

Owner: export-service on-call role.

Scope: queued report generation; not billing, payment or notification delivery.

Entry condition: the existing service alert reports that job age has breached its approved operational limit.

Required access: read-only queue and worker diagnostics for investigation. Production mutations require the incident lead's authorization and the service's restricted operator role.

| Step | Observation, action and stopping boundary | |---|---| | Confirm the target | Match the alert's environment, region, queue and service revision to the service catalog. Stop if they disagree. Never infer production from a resource's display name. | | Classify the backlog | Inspect job age, arrival and completion rates, worker availability and error categories. Record identifiers, not report contents, in the incident record. | | Check dependencies | Confirm whether storage access, quota or an upstream outage explains the failures. If a dependency remains unavailable, escalate to its owner instead of repeatedly restarting workers. | | Contain a confirmed regression | If the current worker revision is implicated, use the service's separately tested deployment procedure only after checking payload compatibility and in-flight work. Capture diagnostic evidence first. | | Verify recovery | Confirm completions resume, oldest-job age trends toward the agreed range and new failures do not increase. Validate a synthetic export's status and private object access. | | Handle retained failures | Keep inspection-queue jobs separate. Do not bulk replay, purge or edit payloads. Open an authorized replay decision covering deduplication, destination, retention and the expected result. | | Close or escalate | Escalate if ownership, compatibility or data integrity remains uncertain. Close only after the incident lead accepts the observed recovery and assigns unresolved jobs. |

This is a triage runbook, not a substitute for the deployment or replay procedure. That boundary matters. Restarting a worker does not prove a job was not already completed, and a queue-depth decline can mean deletion rather than successful work.

In a real runbook, link exact dashboards and approved procedures where the example describes them. Never embed reusable credentials, access tokens or sensitive payloads. Document how to obtain authorized access and how to proceed when it is unavailable.

Treat handover as a test

Ask an engineer who did not write the document to perform the intended task in a safe test environment. Observe where they guess, need hidden permissions or receive different output. Those points are documentation defects or missing operational capabilities.

For the runbook, a rehearsal could introduce a synthetic storage failure, verify that the operator identifies it and confirm that retained jobs are not replayed without approval. Record the environment, service revision, date, tester role, result and unresolved limitations. Do not label a document “validated” merely because someone read it.

Documentation checks can also run with code changes: links resolve, examples parse, commands use the expected version and generated references match their source. These checks cannot establish that an emergency procedure is safe in production.

Google's documentation practices support updating documentation alongside related code and pointing clearly to external authoritative material. Tie updates to behavior changes, dependency changes, incidents, failed rehearsals and ownership transfers. A calendar reminder is a fallback, not the only maintenance mechanism.

Publish with an owner and a retirement path

Give operational documents a status such as draft, rehearsed for a stated environment, or superseded. Show the applicable service version and last verification evidence. Keep sensitive documents access-controlled while ensuring the intended on-call role can reach them.

When a service is retired, remove obsolete instructions from the active navigation and preserve decision history according to the organization's retention policy. Leave a clear successor link where people are likely to arrive through old alerts or bookmarks.

For the next handover, choose one critical operator task and one significant architecture decision. Complete the two records, arrange a safe rehearsal and assign the changes it uncovers. If delivery spans several teams, an engineering pod can include documentation and handover evidence in its agreed acceptance criteria.