The pull request came in on a Friday afternoon. New endpoint, new authentication flow, new response format. The reviewer caught a missing validation step and approved it after a fix. The PR merged. Nobody opened the documentation. Two weeks later, a user filed a support ticket about the authentication flow. The docs still described the old one.
This is the problem that docs-as-code addresses. Not through discipline or reminders, but through workflow.
Docs-as-code is the practice of treating documentation with the same tools and processes as code. Documentation lives in the same repository as the code, written in Markdown or another plain-text format, versioned with Git, submitted and reviewed via pull requests. The same workflow that catches broken code can catch outdated documentation, or at least make the gap visible.
The core benefits are structural. When documentation lives next to the code, changing the code and not updating the documentation requires an active choice to leave the docs behind. The developer who writes the PR sees the documentation files. The reviewer sees them too. The documentation change can be part of the same review, the same conversation, the same commit history.
GitLab’s technical writing team is one of the cleaner examples of this in practice. They produce documentation at large scale, with a relatively small team, using a workflow where documentation changes go through the same merge request process as code changes. The result isn’t perfect documentation — nothing is — but it’s documentation that moves with the product instead of trailing behind it.
CI/CD integration takes this further. You can run documentation linters on every PR: check for broken links, flag passive voice, enforce terminology consistency. These checks don’t replace human review, but they catch the mechanical errors that reviewers shouldn’t have to spend attention on.
Plain text formats like Markdown, AsciiDoc, and reStructuredText have a practical advantage here. They diff cleanly. A change to a documentation file in a pull request shows you exactly what changed, line by line, the same way a code change does. Binary formats like Word documents don’t diff at all; you have to download both versions and compare manually, which nobody does.
This site, doc4docs.com, runs on exactly these principles: Astro for static site generation, Markdown for content, GitHub for version control. The posts you read here go through the same workflow as any other code change. That’s not a technical flex. It’s a practical choice that keeps the content close to the tools I already use.
If your documentation lives in a wiki, a Google Doc, or a content management system that your engineers never open, the gap between what the code does and what the docs say will keep growing. Closing that gap starts with where the docs live.