Docs as code for product managers: what changes when the knowledge base lives in Git

Documentation has a home problem. Code lives in one place, with history and review. The help center lives somewhere else, usually a help desk or a wiki, and none of that history comes with it.

That split is how documentation has worked at product companies for a long time. Engineers ship from Git. Someone on the product side updates the articles afterwards, when they hear about the change. If you own the docs and you're in product, you're probably in this boat.

Docs as code is the fix we chose for Pageloop's own knowledge base, and we think it is the smartest move for product teams in particular. Product moves fast. Releases land weekly, sometimes daily, and the articles have to keep up with that speed or they start telling customers the wrong thing. Keeping the docs in the same repository as the code is the setup where the release and the article move together.

The reasoning behind that choice is in why we built Pageloop on docs as code. Here is what you need to know if you're the product manager who inherited the docs: what you open to edit, how a review works, what engineers do differently (nothing), and what happens to screenshots.

What docs as code means for a knowledge base

Docs as code means the help articles are plain text files, usually Markdown, stored in a Git repository. Every change to an article is recorded with a name and a date. Every change can be reviewed before it goes live. Publishing is a deliberate step, separate from saving.

For a product manager, docs as code means you get those three properties without touching Git yourself. You write in an editor. The editor saves your work as a draft in the repository. When you publish, the repository records the change the same way it records an engineer's code change, and the live site updates.

Why a help desk can't keep up with weekly releases

The setup a product manager inherits is usually a help desk with a draft mode, or a wiki, plus a Slack channel where releases get announced. One product manager we spoke to, at a QR-code product company, approves every help article before it is published from Intercom's draft mode, and releases reach him through a squad's Slack channel. He described the process as one that predates him.

That setup has three weak points, all from the docs living apart from the code.

• Nothing connects a release to the articles it affects. The engineer merges a change, and the article describing the old behaviour stays published until a person notices. In a help desk, noticing means reading the article again, or a customer reporting it.

• A help desk keeps one version of each article. No record of who changed a paragraph, or when, so a wrong article gives no clue which release broke it.

• Drafts leak. A draft mode in a help desk is a single unpublished copy. Two people editing the same article overwrite each other. A half-finished change can go live because someone pressed the wrong button, and there is no review step in between to catch it.

Docs as code answers all three, because the repository already has the tools: a history for every file, a review step before anything merges, and a connection to the code that changed.

The product manager's loop in docs as code, step by step

The loop below is what a product manager does in Pageloop when a release changes something an article describes. Engineers see the same loop from their side as a normal pull request.

1. Open the article in the editor. The editor shows the article as text with formatting, headings and images, the way a help desk editor does. The Markdown file underneath stays in the repository.

2. Edit, and keep a draft. Your edits save to a draft that only you and your reviewers see. The live article stays as it was. You can leave the draft for a day and come back to it.

3. Preview the page. Before anyone reviews, you can open the draft as a rendered page and check that the headings, links and screenshots look right on the real site.

4. Ask for a review. You pick a reviewer, usually the engineer who shipped the change. The engineer sees your edits as a diff: the old sentence and the new sentence, side by side, with a comment box.

5. Resolve the comments. The engineer's comments come back into the editor. You change the wording, they approve, and the draft is marked ready.

6. Publish. Publishing writes your change to the repository with your name and the date, and the live knowledge base updates. The article now has a history entry that says what changed, who changed it and which release it belongs to.

Pageloop runs this loop with one addition. When the engineer merges a pull request on GitHub, or a Linear or Jira issue closes, Pageloop reads the change and drafts the article update for you, with the pull request or ticket attached as evidence. Step one becomes "open the suggestion" instead of "work out which article is wrong". Screenshots get the same treatment: they are image files in the repository, and Pageloop captures the updated screens once you grant it permission and proposes the replacement in the same draft (more in automated screenshot updates for documentation). You still review, edit and publish; nothing goes live without a person.

What "review like a pull request" means without Git

Engineers will use their own words for the loop above. The table maps each word to what it is and what you do about it.

A review on a documentation change is the same review engineers give code. The reviewer reads the diff, leaves comments on specific lines, and approves when the comments are resolved. The difference for you is where you see it: in the editor, next to the paragraph, rather than on GitHub.

What changes for engineers: nothing. Engineers keep their repository, their branch protection and their checks. A documentation change arrives as a pull request they can review in the same list as code. If their repository requires an approval before a merge, that rule applies to the docs too. If they run link checks or style checks in CI, those run on your change as well.

Nobody on the engineering side has to learn a new tool or open a help desk. The docs are files in a repository they already watch. The review shows up where they already work, with the diff they already know how to read. More on getting that review to happen in how to get engineers to contribute to documentation.

When a "hybrid" platform is the wrong fix

The usual objection to docs as code for non-technical teams is that Markdown and pull requests are unfriendly, so the docs should move to a platform with a visual editor and Git should stay with the engineers. That creates a second system, and the two drift again. The fix that keeps one source of truth is an editor on top of the repository: the product manager gets the visual editor, the draft, the preview and the review in plain language, and the engineers keep their files and pull requests. Pageloop is built as that editor and host. It pulls the knowledge base from a GitHub or GitLab repository, publishes it, and connects Intercom, Zendesk, Freshdesk or Salesforce for teams that also run a help desk.

Frequently asked questions

Do product managers need to know Git for docs as code?

No. A product manager using docs as code through an editor never runs a Git command. The editor handles the draft, the review request and the publish step. The words engineers use, such as pull request and diff, describe things the product manager sees in the editor as "ask for review" and "old version next to new version".

What happens to screenshots in docs as code?

Screenshots are image files stored in the repository next to the article that uses them. A screenshot has the same history and review as text: replacing one is a change that a reviewer can see and approve. In Pageloop, the replacement screenshot can be captured automatically once the team grants permission, and it arrives in the same draft as the text change.

How do you move a help center from Intercom or Zendesk into a repository?

The articles are exported as text, converted to Markdown files with one file per article, and committed to a repository with the images alongside. The knowledge base is then published from that repository. Pageloop hosts a knowledge base from a GitHub or GitLab repository and connects to Intercom, Zendesk, Freshdesk and Salesforce, so a team can keep the help desk connected while the articles move.

If you own the docs and you'd like to see what the loop looks like on your own knowledge base, book a demo and see how we fit!