Docs-as-code integration guide
How to keep Docs-as-code up to date
Pages built with docs as code stay in Git, yet nothing in the repo tells you when a change to your product made one wrong.
Keeping help centers accurate at
The short answer
- What Docs-as-code offers
- Documentation as code gives you features like pull request review with CODEOWNERS, CI checks for links and prose, and Git-based last updated dates.
- Where it stops
- Each one checks your docs against themselves or waits for a person to notice, so none can see that a change to your product made a page wrong.
- Where Solo fits
- Solo checks your Markdown and MDX pages against your code, flags what a change made wrong, and drafts fixes that arrive as pull requests a person merges.
On this pageShort answer
Why it matters
Why an accurate docs site matters
Your product changes in the code first, and the Markdown file that describes it sits untouched until someone remembers. Meanwhile readers can't self-serve, AI assistants answer from the old text, and search results quote pages that are no longer true.
Readers solve problems without opening an issue
A page that matches your product lets a reader finish the task on their own. A wrong one sends them to a GitHub issue, a community thread or your support inbox with the same question.
AI assistants answer from your real docs
A chat widget on your docs site or an outside AI tool answers from your published pages, so it repeats whatever they say. If a page still describes a removed option, the assistant gives that answer with confidence.
Your pages show up correctly in search
Search engines index public docs sites, and AI answer engines quote them. A page that still describes a removed setting puts the wrong answer in front of people before they ever open your repo.
Built-in tools
What docs as code tools already offer for keeping docs current
A Git-based docs stack gives you a lot out of the box: history, review rules, CI checks, previews and versioned builds. All of it checks the docs repo against itself, so none of it can see that your product changed.
| Stage | Docs-as-code's features | Missing features |
|---|---|---|
| 01Know upcoming changes | Issue templates in .github/ISSUE_TEMPLATE give readers and teammates a structured form for reporting a page that needs changes, and a GitHub Actions workflow with a cron schedule can run a recurring review job. | Nothing connects the docs repo to your product code, so an issue gets filed only when a person notices a change and thinks to report it. |
| 02Identify outdated articles | Docusaurus throws an error on broken links in a production build by default, Sphinx has a linkcheck builder, and lychee can scan Markdown in CI. Vale lints prose against your style rules, and Git-based dates such as Starlight lastUpdated, enableGitInfo in Hugo docs or a MkDocs plugin show when a page last changed. | These checks look at the docs only, so a page with working links, clean prose and a recent date can still describe a setting your product removed. |
| 03Draft updated copy | Git history and blame show who changed a line and when, and Edit this page links, such as Docusaurus editUrl and Starlight editLink.baseUrl, open the source file in the repo so a writer can fix a page quickly. | Writers draft from their own knowledge of your product, because nothing in the stack proposes replacement text from a code change. |
| 04Collaborate on updates | Pull request review lets a teammate comment on exact lines, CODEOWNERS requests the right reviewers for each docs folder, and branch protection can require approvals and passing checks before a merge. Preview builds, like Read the Docs pull request builds or GitLab Pages parallel deployments, show reviewers the rendered page. | Reviewers see what the docs diff says, but not which change to your product made it necessary, so a review checks the writing more than the facts. |
| 05Publish changes | Read the Docs builds each active version when you push a commit, with latest tracking the default branch and stable tracking the newest semantic version tag. Docusaurus versioning keeps a separate copy of the docs for each version. | Publishing follows a merge, not a change to your product, and each versioned copy has to be edited separately, so an old page can stay wrong after the current one is fixed. |
With Solo
Keeping Markdown docs current with Solo in your Git repo
Your docs repo can review and publish what you write, but it can't see that your product changed. Solo reads both your code and your Markdown or MDX pages in GitHub, flags the pages a change made wrong, and drafts the fix. Each accepted fix arrives as a pull request that your team reviews and merges.
What Solo adds to Docs-as-code's built-in tools
| Stage | Docs-as-code without Solo | Docs-as-code with Solo |
|---|---|---|
| 01Know upcoming changes | Issue templates in .github/ISSUE_TEMPLATE give readers and teammates a structured form for reporting a page that needs changes, and a GitHub Actions workflow with a cron schedule can run a recurring review job. | Solo reads recent code changes in your connected repositories and tells you which Markdown pages they affect, so the writer hears about a change before a reader files an issue. |
| 02Identify outdated articles | Docusaurus throws an error on broken links in a production build by default, Sphinx has a linkcheck builder, and lychee can scan Markdown in CI. Vale lints prose against your style rules, and Git-based dates such as Starlight lastUpdated, enableGitInfo in Hugo docs or a MkDocs plugin show when a page last changed. | Solo compares each code change that affects your product's behavior with your pages and flags the ones now wrong, with the old and proposed text side by side, even when every link and style check passes. |
| 03Draft updated copy | Git history and blame show who changed a line and when, and Edit this page links, such as Docusaurus editUrl and Starlight editLink.baseUrl, open the source file in the repo so a writer can fix a page quickly. | Solo drafts replacement text from your code change and shows it beside the current wording, so the writer edits a proposal instead of starting from nothing. |
| 04Collaborate on updates | Pull request review lets a teammate comment on exact lines, CODEOWNERS requests the right reviewers for each docs folder, and branch protection can require approvals and passing checks before a merge. Preview builds, like Read the Docs pull request builds or GitLab Pages parallel deployments, show reviewers the rendered page. | Each suggestion arrives with your code change behind it and, where the status is available, the feature flag and its rollout state, and your team can edit, accept, reject or snooze it. |
| 05Publish changes | Read the Docs builds each active version when you push a commit, with latest tracking the default branch and stable tracking the newest semantic version tag. Docusaurus versioning keeps a separate copy of the docs for each version. | Once a person accepts a fix, Solo creates a branch and a pull request in your docs repository, or updates an open one on a named branch, and your team merges it so your normal build publishes the change. |
Questions
Questions about keeping Git-based docs current
What teams that keep Markdown docs in Git ask before connecting Solo.
What is a good docs as code workflow for catching pages a change to your product made wrong?
Start with what your repo already gives you: a CODEOWNERS file so the right people review docs changes, CI checks for links and prose, and an issue template that asks which page needs work. Those catch mistakes inside the docs. For changes to your product you need something that reads your code, which is the part Solo adds to a Docs-as-code setup.
What are docs as code best practices for review and ownership?
Give each docs folder an owner in CODEOWNERS, and use branch protection to require review and passing checks before a merge. Add a scheduled GitHub Actions workflow for link checks, since a cron schedule runs on the default branch and no more often than every five minutes. These habits keep a Docs-as-code repo tidy, but they still depend on someone knowing your product changed.
Does a last updated date tell me a page is correct?
No. A Git-based date only shows when someone last edited the file, not whether the page still matches your product. Starlight, MkDocs plugins and Hugo's enableGitInfo all work this way, and they need full Git history in CI because shallow clones can show wrong dates.
Does Solo replace my Docs-as-code toolchain?
No. Your Markdown stays in your repo, and your site generator, review rules and CI keep doing their jobs. Solo suggests changes, and a person merges each pull request.
Does Solo work with my site generator?
Solo connects to the GitHub repository that holds your Markdown or MDX docs, not to a particular site generator. If your source files use another format or live somewhere other than GitHub, confirm that in a demo before you plan around it.
Will Solo merge or publish changes to my docs repo?
No. Accepting a suggestion creates a branch and a pull request, or updates an open pull request on a branch you name, grouped by repository. Your team reviews and merges it, and your normal build publishes the result.
Related guides
Also works with
Solo works with the documentation tools you already use, and each guide covers what is specific to that platform.
Further reading on help center drift
Why Help Center Content Goes Stale After a Product Launch
Why help center content goes stale after a product launch, what breaks behind the scenes, and how support teams can catch the drift before customers do.
6 min read
When to Update Help Center Articles: A Practical Threshold
A calendar-based review cadence misses most drift. Here's a practical threshold for when a help center article actually needs updating, and why it matters.
7 min read
Release Notes to Help Center Articles With AI: What Works
Piping release notes into AI for instant help articles sounds efficient, but it misses the real problem. Here's what keeps a help center accurate instead.
4 min read
See which Docs-as-code pages your changes made wrong
A demo runs Solo against your own code and your docs as code repository, so the pages it flags are the ones your readers would hit.