Maintenance and Efficiency
Documentation Maintenance: Keeping the Description in Step with the System
How to keep documentation in step with the system it describes, by giving each claim an owner, a source, a version boundary and a real verification date.
A team changes the start command, updates an API contract (application programming interface, the agreed way other software talks to yours), changes permissions or moves to a different storage service. The code already follows the new rules, while the README, the instructions for coding agents and the deployment plan still describe the old ones. That gap is not a cosmetic flaw. It forces people and automated assistants to make decisions about a system state that no longer exists.
Documentation is a set of verifiable claims about a particular product, its version and the way it is used. This unit covers document lifecycles, owners and update triggers, generated versus hand-written content, sources and verification dates, changing docs together with code, and checks that test meaning rather than form.
Learning outcome. After this unit the reader can identify which documents a change touches; assign an owner and a source to a claim; tell a historical decision apart from a current instruction; check whether a statement is current and what version and scope it covers; and make a bounded, evidence-backed update without inventing behaviour.
Documentation describes a particular version of reality
A document does not become true because it is written in Markdown, stored in Git or approved in a pull request (PR). To rely on a statement you need to know which system, version, configuration, audience and date it refers to, and then check it against the right source.
The command npm test is incomplete if the repository has switched to pnpm, if the working directory is not stated, or if the tests need a separate database. The phrase "the service encrypts backups" does not say whether that guarantee comes from the product itself, from the external storage, or from how the operator configured it. The statement "Claude reads AGENTS.md" may hold for a specific version and configuration of Claude Code, but not for every Anthropic product.
| Kind of drift | What went stale | Possible consequence |
|---|---|---|
| Command | a command, directory, flag or dependency | the command fails or changes the wrong resource |
| Contract | a schema, format, guarantee or error code | an integration rejects data or mishandles a result |
| Procedural | the order of steps, a stop condition, a permission or the recovery path | the operator deepens the failure or cannot safely roll the action back |
| Status | an intention or plan presented as current fact | someone does cancelled work or believes a feature is ready |
| Architectural | an old decision not marked as replaced | the team keeps building on an assumption it already rejected |
| Scope | version, platform, pricing plan or mode | an example from one environment is applied to another |
| Navigation | an old link, or the current text is hard to find | the reader lands on a copy or an archive |
Distinguish a wrong statement, a missing boundary, a gap and a historical description. "Only Linux and macOS are supported" is not out of date if that is still the exact boundary, even though Windows support is planned. A precise status matters more than the length of the document.
Every document has its own lifecycle
A README explains how to get started; an API reference describes the current contract; an architecture decision record preserves why a choice was made in the past. Rewriting an old decision as if it had never been taken destroys history. Leaving an old active plan without a status forces the reader to assume it is still in force.
| Document | The reader's question | Review trigger | Retirement or replacement |
|---|---|---|---|
| README and introduction | What is this and how do I run it? | a change to startup, requirements or the main function | update the path; remove the old one or narrow its scope |
| API reference | Which contract must I follow? | a change to schema, behaviour, access or compatibility | describe the supported versions |
| Architecture Decision Record (ADR) | Which options and trade-offs were considered? | a new decision or a revisited premise | the new record links to the old one; the old one keeps the history |
| Active plan | What is planned and what is done? | a change of priority, owner, deadline or scope | mark it done, cancelled or superseded |
| Runbook (operational procedure) | How do I perform a known action safely? | a change to commands, access or recovery | check the steps in a defined environment |
| Policy | Which rules and exceptions are mandatory? | a change in risk, control or requirement | record approval, effective date and replacement |
| Course unit | Which principle and example help me act? | a change to a product, interface, feature or link | keep the principle; mark the version of the example |
Statuses such as "draft", "current", "superseded" and "archived" are useful if they are defined and the index leads to the right version. Keep the status of a page separate from the status of a feature: current documentation can correctly say that a feature is not available.
Amazon Web Services (AWS) Prescriptive Guidance advises against rewriting an accepted ADR after the fact. A new record captures the new choice, and the previous one gets the status "superseded" plus a forward link. This is AWS's advice, not the only possible ADR format; the general practice is covered in Architecture Decision Records. AWS: ADR process
Claims need owners, not folders
"The team owns the documentation" does not say who will check behaviour after the code changes. An owner is a person or role able to confirm the content and arrange a fix. The owner of a page may not own every fact on it, so the page should name who is responsible for each critical contract and where that contract's source lives.
| Change | Who checks | What they compare |
|---|---|---|
| Test command, build target, dependency or flag | the build maintainer | the command, tool versions, a clean environment |
| API field, event schema, error | the contract/API owner | schema, compatibility, examples and semantics |
| Backup or storage | the data/procedure owner | the actual artifact, restore and version |
| Permissions, secrets or personal data | the control owner together with a technical specialist | where the control applies, exceptions and logging |
| Architectural decision | the author of the new decision or an assigned owner | alternatives, consequences and earlier records |
| Example of a product's interface | the author of the example or the instructor | source, version, mode and feature boundaries |
| Emergency procedure | the person responsible for operations | steps, stop conditions, permissions and result |
Triggers can be enforced in review: a change to the test configuration requires reviewing the command in the README; a schema change requires reviewing the reference and its examples; a permission change requires reviewing the procedure and the policy. CODEOWNERS on GitHub routes a review request to the owners of the changed files, but it does not prove that those owners are still the right people or that the text is correct. GitHub: About code owners
For critical pages, record the owner's role, the source, the review triggers, the versions covered and the date of the last substantive check. Start with instructions that can affect startup, data, permissions, security or a decision about readiness.
Tie documentation changes to system changes
Docs as code means keeping text in a versioned repository, which gives you history, diffs, review and automated checks. It does not guarantee that the author compared the description with the behaviour.
Build a chain: a change in the source → the claim that changed → the documents that depend on it → a check of each updated claim. Changing the test command in package.json may touch the README, the agent instructions and the contribution template. It does not require rewriting every course unit or historical report. Update exactly the places where the old fact, or something that depends on it, still lives.
When documentation and code change in the same PR, the reviewer sees the contract, the new description and the checks together. If the code has already been merged, create a bounded documentation task, link it to the change and assign an owner. "We'll update it later" with no owner and no deadline does not close the gap.
In the GitHub Docs process, the author checks technical accuracy, style, versioning, how tables and lists render, and the results of automated checks; large proposals can be discussed in an issue first. That is GitHub's own process, not a general standard, but it shows that content review has to cover both meaning and rendering. GitHub: About contributing to GitHub Docs
An example of changing code and explanation together is Pydantic PR #7800. Issue #7784 reported that a model with frozen=True, a setting that forbids changing fields, still allowed an attribute to be deleted. The PR added a deletion check to the implementation, a test, and an example of the error to the reference, and its metadata closes the issue. This shows the value of changing behaviour, test and document together, but it proves no guarantees beyond the case that was checked. Issue #7784; PR #7800
A PR should explain which problem it fixes; which claim it changes; which source supports the text; which version the text is correct for; how commands, examples and rendering were checked; and what is still unknown or out of scope. Instead of a vague pointer to "the code", name the specific schema, file, test or release you compared against.
Generate facts, keep human explanation
Generation reduces drift for details that have a single machine-readable source. It cannot decide which trade-off the team accepted, why a constraint exists, or what to do in a dangerous situation.
| Content | Sensible to generate | Keep hand-written |
|---|---|---|
| API fields, types and endpoints | the reference, from the contract schema | semantics, compatibility, business examples |
| Command-line tool options | the list of flags, from the implementation | safe ordering and the consequences of risky options |
| Settings | names and types, from the schema | precedence, combinations, support boundaries |
| Packages and integrations | the list, from the lock file | the reason for the choice, the risk and the update process |
A generated reference can show that status is a string, but not explain whether pending means "the request is queued" or "the operation can still be cancelled". A list of flags can include force without telling you that it bypasses a data-integrity check. That information is part of the contract and of the risk.
A generator should run against a specific revision, and its output should record where it came from: the source, the command and, where possible, the tool version. Changing the source without regenerating the derived file should produce a visible diff or an error. Do not hand-edit a file the generator will overwrite. The canonical source can be code, a contract or an approved policy.
Check meaning, not just what is easy to automate
A passing link check shows that the address responded; it does not prove that the page is correct or covers the right version. A spell checker does not verify a contract.
| Check | What it confirms | What it does not confirm on its own |
|---|---|---|
| Site build and rendering | structure and display | factual accuracy |
| Link check | the path exists or the address responded | the page's content and whether it is current |
| Running an example in a clean environment | the command works under specific conditions | support for every platform |
| Comparing an API example with the schema | the shape and part of the behaviour | the semantics of every scenario |
| Term and version check | inconsistent names or outdated labels | whether the context is right |
| Owner review | that a responsible person checked it | that the fact will stay unchanged |
For a command, record the environment version and the expected result, or name the platform that was not checked. Do not run dangerous steps on a production system just to earn a "verified" mark: use a safe environment, or check against the code and the preconditions. A restore procedure may need a restore rehearsal, not merely a check that the backup command runs.
Semantic review asks: does the page promise what the implementation does; is the version visible; has an example from one platform been generalised to all of them; does the reader know when to stop; does the entry point lead to the current procedure? GitHub Docs versions its material by product and release and advises checking each relevant rendered variant. The broader principle is the same: name the version you cover and check every variant that matters. GitHub: Versioning documentation
A green build or a passing link check does not confirm that the text matches the implementation, names the right version and leads to the current procedure.
Cite the source, the date and the limits of the check
For a fact that is likely to change, record where it was checked, which version was examined and when. Interfaces, feature availability, limits, compatibility, page addresses and version requirements all change quickly.
A source record should contain the exact link or local artifact; the class of source (code, test, contract, official guide or assumption); the scope (product, version, platform and environment); the date of the actual check; and any uncertainty the source does not remove.
Do not put a new "verified" date on a page after fixing punctuation, translating it or having it automatically rephrased, if nobody opened the source. When only the form changed, the date of the last substantive check stays as it was. A redirect to a new address proves where the link leads, not that the content is unchanged.
In teaching material, separate the durable idea from the changeable example: a file name, a product behaviour or a setting has a version and a date; the principle may stay valid. Re-check an external page before reusing an example.
Shared instructions for Claude Code and Codex
In a repository used by several coding agents, duplicated instructions drift apart: one file says npm test, another says pnpm test; one calls a directory generated, another says it is hand-edited. When they conflict, an agent may silently pick one version.
Start with the shared canonical facts: how to build the project, where the migrations live, which directories are generated, which security rules apply and where the architecture reference is. If a tool supports imports or references, keep the facts in one place and add short tool-specific notes. If it does not, keep the copies short and change them together. Do not duplicate full reference material inside agent instructions.
The mechanisms depend on the product. OpenAI's documentation describes how Codex reads AGENTS.md, takes global and project instructions into account and applies the rules closest to the working directory; its customization overview separates project instructions from memory, skills, MCP (Model Context Protocol) servers and subagents. OpenAI: AGENTS.md; OpenAI: Customization The details are covered in AGENTS.md.
Anthropic's documentation for Claude Code states that reading AGENTS.md directly requires version 2.1.277 or later; before version 2.1.281, certain session types read only CLAUDE.md files. By default Claude Code reads AGENTS.md only when there is no CLAUDE.md or CLAUDE.local.md in the working directory and its parents; otherwise it reads the CLAUDE.md files, including CLAUDE.local.md. An explicit Project instructions setting can load both kinds of file. The built-in agents-md plugin also affects the behaviour. Do not generalise this into "Claude supports AGENTS.md" for every product, version and mode. Check the specific product, version and configuration. Anthropic: Claude Code memory See also CLAUDE.md.
A short repository index should say where the shared facts are, which files add behaviour for a particular tool, and where the deeper references live. Long duplicated instructions are harder to find and to maintain.
Make the current description easy to find
Correct text buried in an old plan is effectively unavailable. The entry point should name the current material and what it is for. Mark a finished plan with a status and a date, or move it to the archive.
Go from a short route to the detail: the root page names the main paths; a section page explains the contents and the versions; the target procedure gives checked steps; the source or history shows the code, contract or decision. For a fact that appears in several places, mark the canonical location and link to it in context. Every unnecessary copy raises the cost of updates and the risk of divergence.
Keep an old ADR, plan or runbook if it explains a past decision, but mark it as historical and link to its replacement. If it is just a duplicate with no historical value, remove it or replace it with a redirect.
Real case: the Gitea restore instructions
Issue #25878 describes a Gitea 1.17.3 user who was restoring the system by following the published procedure and reported that the names and paths in the backup archive did not match the guide. An error about duplicate database indexes also appeared. The issue's author noted that an already initialised database might have affected the result and that the source version needed to be established. This is a user's report, not a full analysis of the database error. Gitea issue #25878
The related PR #26902 updated only the backup and restore page: it aligned the description of the archive contents, moved the path to app.ini to the root of the archive, and corrected the repository directory names for different installation methods. It does not prove that the cause of the database error was found, or that every version and scenario was checked. Gitea PR #26902
The workflow: establish the version and the step; compare the instructions with the artifact produced by that version; separate observation from explanation; fix the relevant passages; check the variants covered; go back to the user's report. Do not claim a broader success than the check supports.
The lesson is limited: a mismatch between the archive structure and the guide can lead to a wrong action during a restore. One issue does not prove that the whole guide is out of date or that every other symptom has the same cause.
Teaching case: a database ADR has gone stale
Suppose ADR 12 recommended PostgreSQL for the first version of a service. A year later the requirements changed, the team evaluated alternatives and chose a different database engine. Do not rewrite ADR 12 as if the old decision had never existed.
A new ADR 27 explains the reason for the review, the requirements, the alternatives, the trade-offs and the scope of the migration. It links to ADR 12 and marks it as superseded. The index shows the current decision. The README and the deployment guide describe the current setup. The old plan is marked complete only after the transition has been verified. If the migration is still in progress, record which environments have already moved, what remains, where the system of record is and what the completion condition is.
Check the configuration, the schema, the migrations, the backups and the restore path. The ADR preserves the history; the current procedure lives wherever the user looks for the action.
When product documentation changes: Claude Code
When checked on 10 October 2026, the old address of the Claude Code memory page redirected to the current page. A moved address is only the first fact to check.
The current documentation says that Claude Code reads AGENTS.md directly from version 2.1.277. Before 2.1.281, certain sessions, including those through Amazon Bedrock or with telemetry disabled, read only CLAUDE.md files. By default AGENTS.md is read if there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory and its parent directories; the Project instructions setting claude-md-and-agents-md can load both kinds of file. If the built-in plugin that reads AGENTS.md is disabled, only the CLAUDE.md files remain.
In the current configuration this setting is stored in pluginConfigs. Before Claude Code 2.1.285 the built-in plugin had the identifier agents-md@builtin; in 2.1.285 it was renamed to cc-plugin-agents-md@builtin, and the current documentation notes that newer versions read the setting under both identifiers. So the old statement "Claude Code reads only CLAUDE.md" is incomplete for newer versions and configurations, and the phrase "Claude reads AGENTS.md" is too broad. Check the exact product, version, settings and the records of the specific run.
A bounded course update should move the link to the official page; state that this is specifically about Claude Code; name the confirmed version and setting; keep the durable idea; and check the example in the corresponding configuration. Do not make an old screenshot necessary for understanding. GitHub Docs advises against versioning small details that do not affect understanding, but recommends checking the variants where behaviour differs. GitHub: Versioning documentation
There are two separate reasons for revision here: the address of the source changed, and support for the feature broadened. Updating only the address keeps the stale content. Updating only the sentence, without the version boundaries, overgeneralises the fact.
A working sequence for an evidence-backed update
- Record the problem: the current text and what has probably changed.
- Find the source: code, contract, configuration, release or official page.
- Set the boundaries: product, version, platform, flag, permissions and environment.
- Find dependent documents: search for the exact command, name, fact or path; separate active text from history.
- Update the canonical location and the links: remove duplicates, keeping history where it explains a decision.
- Verify: run the example safely or compare it with the code or contract; check rendering and navigation.
- Mark the limits of the evidence: leave the source and the date of the actual check; assign an owner to whatever is unknown.
- Review the scope: align related places, remove duplicates and do not rewrite history.
- Bring in a reviewer: the owner checks the fact; the editor checks clarity and navigation.
A finished document lets the reader find the right instruction, see its scope and its source, and tell fact from assumption. A fresh date and a green link check do not replace those qualities.
Sources and further reading
The pages below were checked on 24 September 2026. Official guides describe their authors' practices and products, not universal requirements. The Pydantic and Gitea issues and PRs illustrate specific cases but do not prove causation beyond the limits described.
- GitHub Docs: About contributing to GitHub Docs — issues/PRs and content self-review.
- GitHub Docs: Versioning documentation — versions and checking rendered variants.
- GitHub Docs: About code owners — routing reviews through CODEOWNERS.
- Pydantic issue #7784 — a report of a mismatch between the description and the behaviour of a frozen model.
- Pydantic PR #7800 — implementation, test and error reference changed in one PR.
- AWS Prescriptive Guidance: ADR process — an example of a decision lifecycle.
- OpenAI: Custom instructions with AGENTS.md — how Codex handles project instructions.
- OpenAI: Customization — how instructions differ from other mechanisms.
- Anthropic: Claude Code memory — CLAUDE.md, AGENTS.md, versions and settings.
- Old address of the Claude Code memory page — verified redirect to the current Anthropic page.
- Gitea issue #25878 — a report about restoring Gitea 1.17.3.
- Gitea PR #26902 — the related fix to the instructions.
The content of external pages may change after the access date. Before reusing an example, check the source and the version again; do not carry the verification date forward automatically.