Using AI to Write Internal Documentation Without Making It Worse

Say a team has a restore runbook that was right in March. In October a new engineer follows it during an outage, runs a command whose flag was renamed over the summer, and loses half an hour finding out why. The page looked finished and read well.

An AI assistant can write that page in seconds, from whatever it was given, in the same confident tone. Pages then arrive faster than anyone can check them, and nobody's job is to notice when they stop being true.

This guide gives a small team a way to avoid that: decide what each page is for, let AI work only from sources you supply, make every claim point at a source or show up as a gap, and give each page an owner and a review date. You get a table of AI's role per document type, a copyable prompt, a worked example and a reviewer checklist.

Three ways AI makes internal docs worse

Invented specifics. Asked for a runbook without the script in front of it, a model supplies plausible flags, paths and timings. Anthropic's guidance on reducing hallucinations (fabricated output) recommends explicit permission to say "I don't know" and restricting the model to documents you provide. The same page is plain about the limit: the techniques "don't eliminate them entirely." For the general method of checking AI output, see checking AI output before you trust it.

Blended purposes. Software Engineering at Google describes early wiki pages that mixed links, conceptual background and API reference, and says such pages "fail because they don't serve a single purpose." A request like "document this service" picks no type, so the model has to guess, and nothing stops it blending.

Faster staleness. The same chapter: "Documents without owners become stale and difficult to maintain." AI makes a page cheaper to write, not cheaper to check or keep current, so output outruns upkeep unless upkeep is designed in.

Decide what the page is for, then what AI may do

Diátaxis is a documentation framework by Daniele Procida. It names four reader needs and the form of documentation that serves each. The last two columns of the table are this guide's own working rule for AI's role, not part of the framework.

The rule behind the table: AI formats and drafts text you can point at, and it is not a source. Procida notes that software can generate some reference itself, which keeps it "faithfully accurate to the code".

Not sure which type a page is? Procida's compass asks two questions. Does the content inform action or cognition? Does it serve the reader's study (acquisition of skill) or work (application of skill)? Action plus study is a tutorial, action plus work a how-to guide, cognition plus work reference, cognition plus study explanation. A page that answers two needs should become two pages. His how-to rule is "no digression, explanation, teaching"; if reference or explanation matters, "link to them."

A drafting workflow where every claim points at a source

The steps

1. Name the type and the one question. "How do I restore last night's backup into staging?" Two questions means two pages.
2. Assemble a source packet. Give each item an ID and a date: the script or config at a specific commit, the incident ticket, the chat thread where a decision was made. Strip secrets and personal data first, and use only tools your team has approved.
3. Run the template below, one page at a time.
4. Run it yourself. Execute every command in a disposable or staging environment from a clean shell. For a tutorial, have someone who was not involved do it from the top.
5. Review with the checklist further down, by someone who did not write the prompt.
6. Publish with metadata: owner, type, last-reviewed date, and the source IDs turned into links.

A prompt template

You are drafting an internal {{doc_type}} for {{audience}}.
The page answers one question: {{question}}

Use only the sources below. Do not use general knowledge.
<sources>
{{source_packet}}
</sources>

Rules:
1. Every command, flag, path, name and number must come from a source.
   After each step or fact, add its source ID in brackets, like [S2].
2. If something is needed but is not in the sources, write
   "NOT IN SOURCES: <what is missing>" and do not guess.
3. No background, history or reasons. If a source contains them,
   add one line: "See: <topic>".
4. Format: {{format}}
5. End with a list of any places where two sources disagree.

Output the page and nothing else.

The "use only" line mirrors Anthropic's advice to restrict the model to provided documents, rule 1 its advice to cite quotes and sources, and rule 2 its "I don't know" permission. Together they turn silent guesses into visible gaps a reviewer can fix. They do not make output trustworthy: a model can attach a source ID to a claim the source does not support, so the checklist spot-checks the IDs. For an explanation page, replace rule 3 with "Include the reasons the sources give and attribute each."

Keep the template in the prompt template builder, a free tool that turns {{variable}} prompts into a fill-in form and a local library. The anatomy of a good template is in reusable prompt templates, and a team prompt library keeps one tested version in use.

Worked example: a restore runbook for an imaginary team

Everything here is invented for illustration. Say a three-person team runs a service called Ledgerly and wants a how-to for restoring the nightly database backup into staging. The source packet:

S1 | backup.sh at commit a41f9c2, 2026-09-30 | usage: backup.sh restore --snapshot <id> [--target staging]
S2 | ticket OPS-212, closed 2026-09-02 | "restore fails without --snapshot after the storage move"
S3 | #ops thread, 2026-08-19 | "retention is 14 days now, was 30"

The draft comes back with source IDs, and the reviewer opens each one:

Two of the four errors carry a source ID, so an ID is a lead for the reviewer, never proof. A claim with no ID is a finding.

A reviewer checklist

Software Engineering at Google separates three reviews: technical (accuracy, by a subject expert), audience (clarity, by someone unfamiliar with the domain) and writing (consistency). A small team can cover the first two with the checklist below and one newcomer.

• The page has one type and states the question it answers in its first lines.
• Every command, flag, path, value and number has a source ID that opens to a real file, ticket or message.
• Every source next to a command, a number or a warning was opened and says what the page claims.
• Every claim without a source ID was sourced, measured or deleted, and no NOT IN SOURCES marker is left.
• The commands were run from a clean shell in staging and the output matches the page. (Tutorials: someone new ran it from the top.)
• Destructive steps carry a check-first step and a way back.
• Prerequisites, permissions, versions and names (flags, menu paths, environments) match what the tool shows today.
• A how-to or reference page contains no explanation or opinion; links go to the pages that hold them.
• An owner (a named person or a team that answers questions) and a review date are on the page.

Keeping pages true after they ship

The same chapter treats documentation like code: source control, owners, reviewed changes and periodic testing. Its freshness-date practice is cheap to copy: each document records its last review, and a reminder goes out when it has not been touched for, in the chapter's example, three months.

type: how-to
owner: platform-team
last_reviewed: 2026-10-15
review_by: 2027-01-15
sources:
  - scripts/backup.sh
  - ticket OPS-212

Four habits keep that metadata honest.

• Review on change, not only on a calendar. The sources list shows which pages a change touches. A search finds them: grep -rl "scripts/backup.sh" docs/.
• Make examples executable. A script that runs a page's commands in a throwaway container and fails when the output changes would catch the renamed flag from the opening. Procida notes that when a product evolves quickly, tutorial work must be redone, so give tutorials the shortest interval.
• Update by diff, not by rewrite. When a source changes, give the model the diff and the current page and ask which lines are now wrong. A full regeneration throws away the review the page already passed.
• Retire visibly. The chapter says to remove a document that no longer serves a purpose, or mark it obsolete and point to the replacement. Even a short note that a procedure no longer works beats a page that still looks authoritative.

Where to start this week

Pick the one page someone actually used in the last incident or onboarding, not the whole wiki. Procida's own advice is to take a single page, assess it, decide one action and publish it before moving on.

1. Decide its type with the compass. If it answers two needs, split it.
2. Build the source packet, run the template, run the commands and review it with the checklist.
3. Add the owner and review date, then repeat for the next page.

Verified pages are also the only ones worth converting into other formats such as audio, which turning documentation into audio covers. More is in the AI at work hub.

Frequently asked questions

Can AI write internal documentation on its own?

Not safely. It can draft and reformat from sources you supply, but a model cannot know which flag your team renamed last month or why a decision was made. A person who has run the steps must verify and own each page.

How do I stop AI from inventing steps in a runbook?

Give it the script, config and ticket history as numbered sources, tell it to use only those, let it write "NOT IN SOURCES" instead of guessing, and require a source ID after every command. Then run every command in staging. Anthropic's guidance says such techniques reduce hallucinations but do not eliminate them, so the run-through is not optional.

How often should internal documentation be reviewed?

On a calendar and whenever its sources change. Google's example reminder fires when a document has not been touched for three months; choose a shorter interval for pages about fast-changing systems and a longer one for stable explanation pages.

Do I need to reorganise my wiki into the four Diátaxis sections first?

No. Procida describes Diátaxis as a guide, not a plan, and warns against creating empty sections for each type. Start with one page: decide its type, fix it, publish it, and let the structure form as pages move under the right headings.

Who should review AI-written documentation?

Two people with different jobs. A subject expert who did not write the prompt checks accuracy and runs the commands, and someone unfamiliar with the topic follows the page and reports where they got stuck. Google's documentation chapter calls these the technical and audience reviews. The page's owner answers for it afterwards.

Sources and further reading

• Tutorials - Daniele Procida, Diátaxis (undated site). Defines a tutorial; says it should work "for every user, every time".
• How-to guides - Daniele Procida, Diátaxis (undated site). Defines a how-to guide and the "no digression, explanation, teaching" rule.
• Reference - Daniele Procida, Diátaxis (undated site). Defines reference; generating it from the software keeps it accurate.
• Explanation - Daniele Procida, Diátaxis (undated site). Defines explanation and its place beside the other types.
• The compass - Daniele Procida, Diátaxis (undated site). The two questions that map content to one of the four types.
• Diátaxis as a guide to work - Daniele Procida, Diátaxis (undated site). A guide, not a plan; improve one page at a time.
• Documentation (chapter 10 of Software Engineering at Google) - Tom Manshreck, O'Reilly, 2020. Owners, freshness dates, review types, obsolete documents.
• Reduce hallucinations - Anthropic, Claude documentation (undated page, accessed October 2026). Saying "I don't know", grounding, citations, limits.