dooopSoftware · Process · 11 min

How to Keep Documentation Useful for People and Agents

Learn when changes in interfaces, rules, decisions, operation, or permissions require updating, archiving, or removing documentation.

Published on September 6, 2026

CENTRAL THESIS

Old context becomes an operational risk. Useful documentation blocks closure when it could guide the wrong action.

Update based on real changes, not on a calendar. The criterion is to preserve reliable context for people and agents.

Extensive documentation can remain useless if the change that alters understanding, execution, review, or operation of the software does not appear where people and agents seek context.

The closure criterion is demanding: before closing a change, the team needs to verify if something changed in the context that a person or an agent will use in the next action. If it changed, the documentation must be corrected, marked as obsolete, or removed.

When Documentation Stops Being Useful for People and Agents

Documentation usually starts reliable. It explains an API, records a decision, describes a command, guides a review. A few weeks later, the system has already changed in small points: a parameter was renamed, a rule gained an exception, a test began covering another behavior, a tool permission was altered.

For an experienced person, this lag can be overcome by memory, conversation, or reading the history. This does not make the problem smaller. It only transfers the reliability of the documentation to the minds of a few people.

For artificial intelligence agents, the risk is different. Anthropic defines context engineering as the selection and maintenance of information available to the model during inference, including instructions, tools, external data, and history, within a limited context window (Anthropic). Practically, if old material enters the context, it competes with the correct material.

People interpret gaps. Agents tend to operate based on what was made available. Therefore, living documentation is not synonymous with extensive documentation. It is documentation that preserves trust about what should guide the next action.

This distinction is especially relevant when teams use AI to support specification, review, defect investigation, or code generation. Good documentation does not eliminate human review, testing, or supervision. It reduces the chance that work starts with a wrong premise.

If the organization is still defining its adoption strategy, this point connects to a larger question: what capabilities need to exist before expanding AI use? dooop addresses this in how to create an artificial intelligence strategy connected to business. Here, the focus is more operational: how to maintain reliable context in the engineering flow.

Real Change Is the Trigger, Not the Passage of Time

Periodic reviews have value but should not be the main mechanism to maintain engineering documentation. The calendar finds problems too late. Change finds the problem at the moment it arises.

A documentation update should be triggered when the change modifies any of these points:

an interface used by people, systems, or agents;
a business rule or observable behavior;
a relevant technical decision;
the way to execute, test, review, or publish;
a permission, dependency, tool, or data available to the agent;
the validity of an existing document.

This criterion separates updating from editorial care. It is not about polishing text with every small change. It is about asking if the next person or agent can act wrongly because some information has aged.

DORA recommends small, independent, and testable work units to get feedback on changes and review hypotheses earlier. The same guidance warns about the difficulty of reviewing and integrating large changes generated with AI (DORA). This recommendation is not a rule about documentation but helps think about the process: the smaller and more testable the change, the easier it is to decide which context was affected.

Event-based updating also avoids a common mistake: turning documentation into inventory. Inventory grows. Reliable context guides action.

What Needs to Be Documented to Guide the Next Action

Not all documentation answers the same question. Mixing everything on a single page increases the chance of long, ambiguous, and hard-to-maintain text.

A practical way to organize engineering documentation is to separate four types.

Reference documentation: answers what exists. Includes APIs, commands, parameters, events, data contracts, configurations, and usage examples.
Decision documentation: answers why a choice was made. Includes considered alternatives, chosen option, constraints, and known consequences.
Operation documentation: answers how to execute safely. Includes runbooks, local commands, publishing steps, verification, recovery, and stop criteria.
Instructions for agents: answer which limits must be respected. Include allowed scope, trusted sources, permissions, prerequisites, available tools, and points requiring human review.

Separation matters because a small code change can affect more than one type of document. Changing an API parameter is reference. Changing the reason why a flow avoids an external dependency is decision. Changing the test command is operation. Changing which files an agent can edit is agent instruction.

GitHub’s documentation about Copilot agents describes features with distinct environments and permissions and emphasizes human supervision and output review (GitHub). In the engineering flow, this supports an operational rule: environments, permissions, and limits must be explicit where they guide action.

An agent should not receive a generic document trying to explain the entire system. It needs selected, current, and proportional context to the task. A person also benefits from this. The gain is not in writing for the machine. It is in writing so that the next action can be taken with less guesswork.

Questions to Detect Obsolete Context

The proposal of this guide is to use documentation as a criterion for closing the change. Before closing a pull request, card, or task, the team answers whether the change affected any of the points below. If yes, the corresponding documentation needs to be updated, marked as obsolete, or removed.

Did an interface used by people, systems, or agents change?

Update API documentation, data contracts, commands, parameters, usage examples, or call instructions. The risk of ignoring this is simple: the next execution may follow an input, output, or sequence that no longer exists.

Did a business rule or observable behavior change?

Update the rule explanation, edge cases, expected messages, and test examples. If this becomes outdated, people and agents may preserve the previous rule in new changes.

Did a relevant technical decision change?

Update or create a decision record explaining the chosen option, discarded alternatives, and known consequences. Without this, the team may reopen already resolved discussions or automate a solution against the architectural intent.

Did the way to execute, test, review, or publish change?

Update runbooks, local commands, review criteria, mandatory tests, and recovery steps. The risk is that documentation guides a sequence that fails or leaves a check out of the flow.

This point connects to continuous integration. DORA describes continuous integration as frequent integration into the main code, accompanied by automated builds and tests, and states that fixing a broken build should have priority over new changes (DORA). If the testing method changed but the documentation did not, the flow becomes dependent on informal knowledge.

Did a permission, dependency, tool, or data available to the agent change?

Update agent instructions, access limits, prerequisites, and trusted context sources. Otherwise, the agent may try to act with a capability it does not have or use information outside the scope.

Does the change make any document misleading?

Correct, archive, mark as obsolete, or remove the content. It is not enough to create a new page if the old one will still be found. The volume of documentation increases but trust decreases.

Is the change small, independent, and testable?

Record only what is necessary for the change to be understood and reviewed. Avoid turning a small change into a broad documentation rewrite. When documentation updating becomes a heavy ceremony, the team learns to skip the process.

Fictional Example: A Small Change That Alters Context

In a fictional example, a team maintains a product with access invitations for new users. The old rule said invitations expired after a fixed period. A small change alters the behavior: resent invitations now reuse the original expiration instead of restarting the deadline.

The code changes little. Perhaps a function, a test, and a message. But the context changed in points that affect the next action.

API documentation needs to indicate the expected behavior on resending. Decision documentation can record why the original expiration was preserved. Operation documentation can update what the team checks when investigating an apparently expired invitation. Agent instructions should prevent the next task from "correcting" the behavior by recreating the old rule.

None of this proves gain. In a real case, effects would have to be measured: less rework, fewer repeated doubts, clearer reviews, or lower incidence of changes that reintroduce the previous rule. The point of the example is different: a small change can alter context in a relevant way.

If the team is using AI for defect investigation or to suggest tests, the old rule in documentation can lead to wrong hypotheses. If a new person joins the team, the same lag creates dependence on someone who "knows how it ended up."

Useful documentation is the one that prevents this deviation before it becomes a habit.

How to Avoid Excessive and Dangerous Documentation

The opposite of abandoned documentation is not total documentation. It is documentation proportional to the risk of misunderstanding.

Some changes do not require a new page. An internal adjustment without observable effect, without new decision, without command change, without test impact, and without permission change may require no more than a good description in the pull request itself.

Other changes require removal, not addition. If an old instruction continues appearing in internal searches, context files, or examples copied by agents, creating a new page may worsen the problem. The reader finds two versions. The agent may receive the wrong one.

There are three useful criteria to avoid excess:

write in the smallest place that will still be found by the next action;
prefer correcting the existing context source rather than creating a parallel explanation;
mark obsolescence when immediate removal could break history or traceability.

Dangerous documentation is the one that seems official but guides an invalid action. It is worse than absence of documentation in some flows because it reduces the team’s willingness to ask, test, or review.

This care also applies to strategy. Organizations building an AI roadmap tend to discuss use cases, tools, and prioritization. But the ability to maintain reliable context should enter the conversation because agents amplify both the reach of good instruction and the damage of aged instruction.

How to Make Documentation Updating an Engineering Habit

The habit is born when the question enters the change closure, not when someone schedules a cleanup task force.

A simple flow can work like this:

during implementation, the responsible person identifies if the change affects reference, decision, operation, or agent instruction;
in review, the reviewer checks if any document became misleading;
before closing the task, the team records the update made or explains why it was unnecessary;
when documentation is wrong and could guide future work, correction receives priority compatible with the risk.

This does not need to depend on a specific tool. It can be in a pull request checklist, in a card acceptance criterion, in a review policy, or in a task closure script.

The rule needs to appear in the work closure. If documentation is treated as a subsequent task, it loses to the next urgency. If treated as part of the change closure, it becomes a reliability condition of the flow.

It is also not a defense of automation without judgment. Agents can help locate possibly affected sections, suggest updates, or compare contradictory instructions. Still, someone needs to decide if the documentation change is correct, sufficient, and safe. Human review is not late correction. It is part of the process design.

In a maturity assessment, the relevant question is whether the team knows when a change requires context updating. This difference appears in broader capability diagnostics, such as in AI maturity, but can start in a very concrete engineering practice.

As a closure rule, define which types of change block closure while documentation, agent instructions, or decision records remain misleading. The first block should be on what can guide a wrong next action.

Sources

NEXT DECISION

Discussing Application in the Company

Conversation about the software company context

Content by dooop. Registration allows relating this topic to the reader’s journey and tracking interest in the subject.