import DefinitionCard from "@site/src/components/DefinitionCard"

# AI Documentation Writing Workflow

_Draft from authoritative sources, then verify the document as a reader would use it._

## Introduction

AI can turn code, specs, and notes into a first draft. It also makes up believable commands, options, and behavior wherever the source runs thin. Treat the draft as raw material, not a result.

This works for guides, tutorials, concept articles, runbooks, and architecture records.

## Understanding the Workflow

Start with an **audience contract**. It names the reader, says what they already know, and says what they should be able to do once they finish.

The draft has to come from **authoritative sources**: current code, commands you have run, API schemas, real product behavior, and design records the team accepted. Search results and an old article give you leads, not facts about how the thing works today.

Review the draft against three criteria:

| Criterion | Question |
| --- | --- |
| Technical accuracy | Does every factual claim match the source and current version? |
| Reader fit | Can the intended reader understand the terms and assumptions? |
| Task completeness | Can the reader reach the stated outcome using this page? |

## Applying It in Practice

Prepare the prompt with:

- the audience contract
- the document type and required structure
- relevant source files or specifications
- terminology and style rules
- scope boundaries
- commands used to validate examples and links

Ask for a whole draft when the sections lean on each other. Ask for one narrow edit when the shape is already right.

Check the technical claims first. Run the commands, compile the examples, follow the links, and compare every name and default against the installed version. Cut anything you cannot trace to a source.

Then read it as the reader. Define a term before you use it, add the prerequisites they will need, and cut the implementation detail that does not get them to the outcome.

Walk the whole thing through using nothing but the page. Write down every missing step, unclear choice, and failure you hit. Someone else from the target audience is the strongest check you can get.

Run the formatter, the linter, the link checker, and the production build. Preview the rendered page to catch broken components, bad headings, and code blocks nobody can read.

## Engineering Considerations

Fluent prose can hide factual errors, the documentation form of [AI slop](/learn/concepts/ai-engineering/ai-assisted-software-engineering). Verify details before polishing sentences, because a clear false statement is still harmful.

Keep generated examples small enough to run. If one cannot run as written, say so, and never dress up invented output as something you observed.

Let a generator handle the mechanical facts, such as function signatures. Write the guides yourself for task order, decisions, and explanations. No generator can tell you what a reader needs to know.

Documentation changes should ship with the behavior they describe when possible. That keeps reviewers close to the source and reduces drift, and it fits naturally into an [AI feature development workflow](./ai-feature-development).

## Scaling and Operations

Give each docs area an owner, and put docs in your definition of done. No amount of automated drafting makes up for nobody owning the page.

Keep shared audience definitions, terminology, and style rules somewhere both writers and agents can read them. Keep prompt templates short and tied to a source.

Track the pages that depend on a versioned API or command. Run the runnable examples in CI where the upkeep is worth it, and flag a page for review when its source files change.

Put trust ahead of volume. Ship fewer pages you have checked instead of filling gaps with drafts nobody has read.

## Next Steps

- [AI Code Review Workflow](./ai-code-review): apply evidence-based triage to code findings
- [AI Marketing Copy Workflow](./ai-marketing-copy): draft product copy from a controlled brief
- [AI Feature Development Workflow](./ai-feature-development): document the behavior produced by a feature
- [Human-in-the-Loop Review Workflow](/learn/workflows/git/human-in-the-loop-review): require human approval for generated work