Docs as code, without asking PMs to learn Git

What docs-as-code means for product

The repo is where product truth lives — the code, the reviews, and increasingly the AI agents that write code all work there. Docs as code puts the documents that shape the product's future in the same place as the code that defines its present: specs are plain Markdown files in the repository, every change has an author and a timestamp, and review happens in the open instead of in a comment thread nobody revisits.

Why Notion and Google Docs break the loop

A spec in Notion or Docs starts drifting the moment engineering picks up the work. Engineers read it once, build from the ticket, and never come back; changes made during implementation never flow into the doc; and six months later the spec describes a product that no longer exists. The doc app has its own permissions, its own search, and its own graveyard of stale pages — all disconnected from where the product is actually decided. On the blog: why specs go stale and a fair Notion vs GitHub comparison. If Notion is the incumbent you are actually trying to replace, there is a longer rundown of Notion alternatives for product docs.

Shared-drive UX on the repo

specgit makes a GitHub repository feel like a shared drive. You browse files, open a doc, and write in a visual editor — formatting toolbar, inline comments, live co-editing with teammates. Behind the scenes, every save is a commit and drafts are real branches, but nobody on the product side has to know or care. Import existing Word, PowerPoint, Excel, or PDF files and they're converted to clean Markdown in your repo.

Review like a pull request

When a draft is ready, teammates review it the way engineers review code. Inline comments are pull request threads; approvals count toward branch protection and required-review rules; and publishing merges the doc to your base branch. specgit shows exactly what's blocking a publish and can publish automatically the moment required approvals land — so reviews finish instead of stalling.

What a docs-as-code workflow looks like for a PM, step by step

None of this involves a terminal. The whole loop runs in the browser, and the Git your engineers see on their side happens as a side effect of it.

1. Sign in with GitHub and pick the repository the spec belongs in. An individual can install the specgit GitHub App on their own account; for an org repo, an admin installs it once and members can request it in a click.
2. Open a Markdown or HTML file that is already there, start from a template (product spec, backlog tracker, decision record, meeting notes, agent instructions), or upload the Word, PowerPoint, Excel, or PDF version you have been maintaining and let specgit convert it to Markdown.
3. Write in the visual editor, with a formatting toolbar, inline comments, and teammates editing alongside you. Saving is automatic, and each save is a commit on a draft branch, so what you are working on never overwrites what the team is reading on main.
4. Read your own redline before anyone else does. View changes shows the draft against main and lets you undo individual edits instead of the whole session.
5. Send it for review. Publishing opens a pull request, you request reviewers from the publish menu, and their inline comments come back as review threads you answer in the editor.
6. Publish, which merges the doc into your base branch. If the repo requires approvals, specgit says what is still missing and can hold the merge until the last approval lands.

Between steps, unpublished drafts sit in a Continue working list, so a spec you left half-written on Thursday is one click away on Monday. If some of your writers are not PMs at all, the same flow is covered for non-technical contributors.

What changes for engineers: nothing

That is the point of the whole exercise. A spec arrives as a pull request on a branch, with a plain-text diff, in the same review queue as the code. Branch protection, required reviews, and rulesets apply exactly as they do everywhere else. Engineers can answer a comment from GitHub and the PM sees it in specgit, or they can review inside specgit under their own GitHub identity. There is no second tool to install, no second account, and no second permissions system to keep in sync.

The automation carries over as well. CODEOWNERS assigns the reviewer, the Actions your repo runs on pull requests run on the doc too (link checkers, Vale or another style linter, the docs site build), and specgit tells the author when a publish is waiting on those checks rather than on a person. Where the repo already builds a site from its base branch, the merge that publishes the spec is the merge that ships it. specgit is not the renderer or the host, so themes, domains, and reader-facing search stay with that pipeline.

The files stay honest, too. A rename in specgit is a real git rename rather than a delete plus an add, and Markdown syntax specgit does not recognize survives a save byte-for-byte. If you are weighing this against a hosted docs platform, the specgit vs GitBook comparison covers where each one fits.

AI agents read the same files

AI coding agents work in the repository — that's where they look for context. A spec that lives next to the code is context they use automatically; a spec in a separate app is invisible. Keeping docs in the repo means engineers and their agents build from the current spec, not a stale copy. specgit also includes an optional AI co-editor, specgit AI, that works on those same files — every proposed change requires your approval.

Getting started

Sign in with GitHub through the specgit GitHub App — fine-grained, repo-by-repo permissions you approve on GitHub, no separate password. Open any Markdown or HTML doc already in your repository, or create a new one from a starter template (product spec, decision record, meeting notes, and more). The Free plan needs no credit card, and there's an interactive demo on the homepage if you want to see the editor first.

Frequently asked questions