What is docs as code, and why we built Pageloop on it

What is docs as code?

Docs as code is a way of managing documentation where every page is a plain text file, usually Markdown, stored in a git repository, and is reviewed the same way your product code would be.

In practice, documentation stops being something you edit in a browser and save. When someone wants to change a page, they propose the change, and it opens as a pull request: the old text and the new text side by side, approved by a teammate before it goes live.

The repository keeps a history of every change, so you can see who changed a sentence, when they changed it, and what shipped alongside it. A wrong edit rolls back to the previous version instead of being reconstructed from memory. And the checks your engineers already rely on, like catching broken links before customers find them, run on the docs too.

This model has been around for years and has become the default for developer documentation. It is also what we chose when we built Pageloop's own hosted knowledge base, and the next section is the reasoning.

Why we put git under our knowledge base

Pageloop's job is keeping documentation true to a product that keeps shipping, and part of that product is hosting the documentation itself. When we designed the hosted knowledge base, we had the same choice every documentation tool faces: store pages in a database with an edit log, or store them in git.

We went with git, because underneath the file formats and the pull requests, docs as code is really four promises: a review before anything publishes, a full history of every change, rollback in one action, and the ability to write docs for a feature before the feature is live.

Engineering teams have been lucky enough to have had these guarantees for twenty years, and I promise you they're not giving those up anytime soon. Documentation, meanwhile, mostly runs without them. In the case of code, it waits for a reviewer, whereas a help article goes live when one person clicks publish, which is easy, but when the article turns out to be wrong, the previous version exists only in someone's memory.

For a long time that gap was tolerable, because a human wrote every article and a human could be trusted to be careful. What changed is that AI now reads your docs and answers customers from them, and AI now writes docs too. The moment a model is drafting your updates, review before publish stops being engineering hygiene and becomes the whole safety model. Every machine-written change needs to pass through a gate a human controls, with the change stamped in history and reversible if it turns out to be wrong. Git has been doing exactly that job for code for twenty years, which is why we put it under our knowledge base rather than a CMS with an edit log.

The question docs as code never answers: who writes the change

Docs as code decides where documentation lives and how a change ships. It has never decided who writes the change.

For API reference, that question mostly answers itself, because the documentation can be regenerated from the spec whenever the spec changes. UI documentation has no spec. A walkthrough of a settings page is prose someone wrote, so when the page gets rearranged, there is nothing to regenerate it from, and the screenshot underneath it has nothing to derive from at all. The change was announced in a Linear ticket and a Slack message. The person who knows what happened is the PM who shipped it, and the pages it broke are somewhere in a help center nobody has opened since March.

That gap, between the release that happened and the person who would have to write it up, is exactly what we built Pageloop around.

How Pageloop runs docs as code without anyone learning git

Pageloop watches your release tools, finds the published pages a release affects, and drafts the correction as a pull request. You approve it before it merges.

The release can arrive as any of the signals your team already produces:

• A Linear ticket moving to done

• A merged GitHub pull request or a resolved Jira issue

• A message in the Slack channel where your PMs post what went out

• A pasted PRD, release notes, or the transcript of a walkthrough

We put most of the work into finding the affected pages, because a release rarely breaks only the pages you would guess. A feature rename needs to get caught on pages that never mention the new name, and an interface change needs to surface every walkthrough that steps through the old layout. With a complex UI, this is where the time goes, because the honest answer to "which pages did we just break?" is usually that nobody knows.

The diff stays small. Pageloop locates the exact string that went stale and replaces it, leaving the rest of the document untouched. We went this way because a reviewer who gets a rewritten page has to re-read all of it, whereas a reviewer who gets three changed lines actually reviews them. Your formatting survives and your git history stays legible. The correction also comes back in your style, because Pageloop reads your published articles and your style guide before it writes.

Nothing publishes on its own. Every change waits in a queue, old text and new text side by side, until a person approves it. We could push changes live without review, and it would be easy, but we built the queue instead because we believe humans should always make the final call on what customers read. AI drafts well, and it still isn't something you hand the last step to. So our job is making that final call fast: you open the change, the old and new text are side by side, and you approve or send back in seconds.

The approved change lands as a pull request against your own repository. Pageloop works with Mintlify, GitBook, ReadMe and custom git repos through the GitHub API, so there is nothing to install and no build step of yours to change. Docs that live in a help center run the same loop, publishing back to Intercom, Zendesk or Freshdesk instead. Teams that would rather not run a docs site can host with Pageloop directly.

Navigation rides in the same pull request: a new page gets placed into your docs.json or mint.json for you. And screenshots get flagged when they no longer match the product, which we covered in finding and fixing outdated screenshots.

Frequently asked questions

Is docs as code only for developer documentation?

No. Docs as code works for any documentation stored as files in a git repository, and that includes customer help centers and product guides. Developer docs got there first because engineers already lived in git, but nothing about the model is specific to code. Pageloop runs the same update loop across git-backed docs and help centers on Intercom, Zendesk and Freshdesk, so a product team can keep both on it without running two workflows.

Do you need to know git to use docs as code?

No. Pageloop's review queue runs in the browser, the draft is already written when you open it, and the approved change is committed to the repository for you.

Can AI update docs as code documentation automatically?

AI can draft documentation updates for a person to review, and should not publish them unreviewed. Pageloop drafts the change from your release signal and holds it in an approval queue until someone accepts it.

What is the difference between docs as code and a help center?

Docs as code stores pages as files in a git repository with pull request review; a help center stores them in a hosted editor with a publish button. Pageloop supports both, and can host your documentation directly.

Bring a release you shipped last month

If you want to see this run against your own docs, book a demo and bring a release you shipped recently.

Image Courtesy - National Gallery of Art
Joseph Mallord William Turner Artist, British, 1775 - 1851