Docs-as-code put your documentation in markdown, in the repo, versioned next to the code it describes. GitBook and tools like it sync straight from a docs/ folder. Agents now write a good share of those updates.
docs/getting-started.md
The docs page covers the response format.
The API returns XML. The API returns JSON as of v2.
An agent edit, caught in review.
Docs-as-code was supposed to fix documentation drift. Put the docs in the same repo as the code, update both in one change, and they stay in sync. Mostly, it works.
But the people who should approve a docs change, a PM, a technical writer, support, do not usually live inside pull requests. So a doc edit either gets rubber-stamped by whichever engineer is closest, or it merges with nobody reading it at all.
An agent that can open a PR to update docs is not the same as a team that reviews what the docs now say.
What docs-as-code means and why teams adopt it.
gitbook.comSyncing a hosted docs site straight from a markdown folder in git.
draftview.appA walkthrough of the docs-as-code review workflow end to end.
blog.markdowntools.comNotes on markdown for technical writers working docs-as-code.
A pull request is built for reviewing code. Line numbers, red and green, a diff algorithm tuned for syntax. Handing a technical writer that view and asking them to judge whether a paragraph still reads well is asking them to work against the tool, not with it.
Most non-engineers either learn to tolerate the diff view or stop reviewing docs changes at all. Either way, the review that docs-as-code promised quietly stops happening.
Open your docs/ folder in Stet and an agent's doc update shows up as a proposal you accept or reject, read as a finished page, not a diff. The people who own the docs can review them without opening a code tool at all.
Leave an AI note asking the agent to fix a section on its next pass, and check the page's history to see exactly how it evolved.
Download the starter kit. It has a GitBook-compatible docs/ folder, a summary file, and a getting-started page ready to edit.
docs/getting-started.md with one real detail about your project.