AI can help teams find documentation affected by a product change, prepare revisions and check examples. Keeping those documents accurate requires a connection to the product version they describe, evidence that the instructions work and a person responsible for the result.
The difficult part often arrives after a page is published. A setting moves, an authentication method changes or a product gains a new exception. The old instructions still look reasonable. A reader may follow them successfully until the final step reveals that they describe a different version of the product.
The right unit of work is therefore a product change and its documentation consequences. This article uses an illustrative authentication update to show how AI can help a team discover, revise and verify those consequences without turning its documentation into an unchecked stream of generated prose.
Follow one change through the reader's experience
Imagine a software service replacing account passwords in its command line tool with browser based sign in. New installations should use the new method. An older supported client continues using the previous flow during a migration period.
The change affects the getting started tutorial, authentication reference, troubleshooting guide, support answers and several examples embedded in unrelated integration pages. A page search for the old command finds some of them. It may miss a screenshot, a description of where a credential appears or a translated guide that uses different terminology.
Give an agent the approved change description, the supported version boundaries and access to the relevant documentation. Ask it to propose an impact inventory. Each entry should name a page, identify the claim that may be affected and explain the evidence connecting it to the change.
Treat the inventory as a review queue. An agent finding a related word has not established that a page is wrong. Conversely, a page with no matching terminology may still describe an affected workflow.
GitLab's documentation workflow explicitly includes documentation for changes to interfaces, workflows and previously documented behavior. The useful principle is to make documentation impact part of the product change while the responsible people still have its details available.
Match the revision to the kind of document
A tutorial teaches someone through a learning experience. A task guide helps them complete a particular job. A reference describes precise behavior. An explanation develops understanding. These four needs are central to the Diataxis documentation framework.
AI should receive a different assignment for each. In the authentication example, the tutorial needs a successful path for a new user. The reference needs exact supported behavior. Troubleshooting needs a recognizable symptom and a recovery path. An explanation may discuss why interactive sign in and unattended automation use different credentials.
Trying to merge these into one comprehensive page can make every reader work harder. A new user should not have to navigate all migration exceptions before completing the basic tutorial. An operator diagnosing an older client needs those exceptions immediately.
The following inventory keeps the revision focused:
| Document | What the reader needs | What must be verified |
|---|---|---|
| Getting started tutorial | Complete a first sign in | A new user can finish the steps on the intended client version |
| Authentication reference | Identify supported methods and conditions | The documented methods match the released product |
| Troubleshooting guide | Recover when the browser cannot complete sign in | The symptom, environment and recovery steps correspond |
| Migration instructions | Move an existing installation safely | Older supported clients remain clearly distinguished |
This is an editorial plan for the example, not documentation of a particular authentication product. The same approach works for a changed billing rule, a renamed setting or a revised deployment procedure.
Give the agent an evidence package
A model can produce convincing instructions from a feature name and an old page. That is an unreliable starting point when the product behavior has changed.
Prepare a small evidence package containing the approved behavior, a release or build identifier, supported environments and relevant existing pages. Include known limitations and decisions about terminology. If a detail is unresolved, label it as unresolved so the draft can carry a question to the owner.
Separate what the interface shows from why the company chose the design. A code change may establish that an option exists, but it may not explain the recommended customer workflow. A product decision may describe the intended behavior before that behavior is present in a released build.
For the sign in update, ask the agent to associate each proposed instruction with evidence: a verified interface label, a documented product rule or an observation from the release candidate. Keep those associations in the review record. They need not appear as annotations throughout the public guide.
Our article on building an AI knowledge base explains how source ownership and access affect shared knowledge. Documentation maintenance adds a specific question: which published instruction does this new evidence require us to change?
Draft the smallest complete correction
Ask for a proposed edit to each affected passage, with surrounding context preserved. This makes a review more useful than receiving an entirely rewritten guide after a small product change.
In the tutorial, replace the obsolete sign in steps and update the expected result. In the migration guide, add the applicable client versions and explain when the old instructions remain valid. In troubleshooting, check whether a previously recommended workaround still applies.
Do not allow the model to silently invent an option that makes the narrative easier. A missing fallback becomes a question for the product owner. A confusing error becomes a product or documentation issue with an assigned owner.
Keep terminology consistent across the set. A command line option, a visible button and a conceptual term may have different naming requirements. Exact interface labels should match the interface, even when an editor would prefer different prose.
The result should be a readable change that a technical owner can assess. Extensive rewriting is appropriate when the structure itself fails the reader, but it needs a clear reason beyond making the page sound new.
Verify the instructions independently of the draft
For the new tutorial, begin with a clean test account and the client version the guide names. Follow the published sequence in order, including setup assumptions. Verify the visible result after each meaningful step.
A reviewer should record whether the instructions worked, which environment was used and where the evidence is retained. A draft generated from code and a second model agreeing with it do not establish that the reader can complete the task.
Code examples need additional care. Where an example is intended to run, execute it with controlled inputs in an appropriate test environment. Check the documented output and the failure path. Do not treat a syntax check as evidence that an authentication exchange, network call or external action succeeds.
Some procedures cannot safely run during routine editorial review. Record the verification boundary, identify the responsible technical reviewer and avoid implying an execution that did not occur. Destructive operations need a separate, deliberate test plan.
For the authentication update, test both the new client path and the still supported older path. Check navigation between them. A correct older guide becomes misleading if search results or the site's default links present it as the current instructions.
Publish with the release, then watch for disagreement
Assign an owner to the affected set of pages. Record which release requires the update, who verifies technical accuracy and who reviews the final wording. If the product ships before the documentation is ready, make the unresolved work visible with a responsible owner and a defined follow up.
GitBook's guidance on documentation accuracy emphasizes ownership, release connections and review against authoritative sources. These practices help establish a maintenance process that continues after the first draft.
Useful monitoring looks for reasons a page may have become incorrect: a changed feature, a failed example, a support report or a reader unable to complete a procedure. Page age can help prioritize review, but it does not determine accuracy by itself.
In the example, a later release changes how the command line tool handles a missing browser. That change should reopen the relevant tutorial and troubleshooting review. The team should not wait for a reader to discover the mismatch.
Translations and supported product versions need explicit treatment. A correction may apply to several editions, or only to one. Keep that applicability visible so an automated edit cannot spread current instructions into a guide for an older release.
Measure the reliability of the reader's task
Generated page count is a poor measure of documentation quality. A useful review asks whether readers can complete the intended work and whether errors are found before publication.
Track the procedures that failed verification, corrections discovered after release and recurring support questions about the documented workflow. Interpret these alongside changes in readership, product use and the kinds of customers involved. Fewer questions alone do not establish that documentation improved.
For an AI assisted process, also inspect the rejected edits. Did the agent miss a supported version, invent a parameter or remove an important exception? Turn recurring problems into specific review checks and representative evaluation cases.
Our guide to LLM evaluation explains how to test AI behavior against known cases. For documentation, the cases should include a small product change with a clear expected correction, an unaffected page that should remain unchanged and a missing fact that should produce a question.
Keep the maintenance record in Swarm
A Swarm Space can retain the change description, affected pages, agent proposals, verification evidence and review decisions for a documentation initiative. People and connected agents can continue from that shared context as a release develops.
For the sign in update, create work around the affected document set. Keep the approved behavior and version boundary available, save proposed revisions as outputs and record the technical owner's decision. Use authorized tools for repository or publishing actions, with access appropriate to the material being reviewed.
The next release can begin with a record of what was verified and why the instructions took their current form. AI helps locate and prepare the work; the team retains a clear basis for deciding that a reader can trust it.