AI-assisted authoring
This page explains how I use AI in a docs-as-code workflow: where it speeds up drafting, where it needs constraints, and how I prevent errors and terminology drift.
Tools in the workflow
- Cursor: primary editor for drafting, restructuring, and refactoring, in the same project as the source repository.
- VS Code with Copilot: secondary editor when working in repos where Cursor is not set up.
- OpenAPI tooling: deterministic, not AI; included here because it works with AI assistance to keep API reference content current.
How I use it
AI is most useful at three points in the workflow and least useful at one:
1. Scaffolding first drafts
I describe the audience, page goal, and constraints, then use the model to generate an outline: sections, headings, and order. The outline is useful because it surfaces layout and section-order issues earlier than starting from a blank page.
2. Restructuring existing content
When a page has become difficult to follow, AI is useful for proposing reordering, identifying duplicated explanations, and flagging sections that no longer match their headings. I treat the suggestions as a starting point for review, not a directive.
3. Tightening prose
AI saves the most time when tightening prose with low accuracy risk because the underlying facts are already in place. Typical passes cut hedging language, break up long sentences, and normalize terminology.
4. Knowing where not to rely on it
- Accuracy-critical content. I verify code samples, API contracts, version-specific behavior, and anything a reader might copy and run against the implementation, not the model.
- Final voice. The model is useful for first drafts; I do the final pass to preserve product-specific tone and terminology.
Constraints
- Technical review is required. AI accelerates drafting; it does not replace the review loop with engineers and product owners.
- Style guide as source of truth. Terminology, capitalization, and product naming follow the project's style guide, not the model's defaults.
- Pull-request review for every AI-assisted change. Each change goes through the same pull request and review process as any other update. If reviewers can't confirm a passage is accurate, I rewrite it until they can.
Impact
- Faster first drafts. The outline-to-reviewable-draft cycle takes hours instead of days for new pages.
- Fewer terminology mismatches. Tightening passes catch terminology drift across long pages and across the site.
- Less switching between tools. Authoring, restructuring, and reviewing all happen in the same editor, against the same source-controlled content.
What this means for the system
AI assistance augments the docs-as-code workflow; it doesn't replace it. The pipeline, review process, and source of truth stay the same. The model shortens the path from draft to reviewable content and reduces terminology drift.