Docs as code with non-technical contributors

The gap this fixes

Docs as code works. Docs live in the repo, changes go through review, CI catches broken links and style violations, and the site rebuilds on merge. The problem is who can participate. The workflow assumes a person who is comfortable with a terminal, and most of the people with the information are not that person.

So you get workarounds. The PM writes the update in a doc app and pastes it into Slack for someone to transcribe. Support files a ticket describing a wrong sentence and waits a week. A designer marks up a screenshot. Each one puts a human relay between the person who knows the answer and the file that needs to say it, and the update usually dies at one of those handoffs.

The GitHub web editor is the usual half-fix, and it is genuinely better than nothing. But it hands a non-developer raw Markdown, a commit message field, and a branch dropdown, which is roughly the same ask with a nicer background color. The contribution rate does not move.

What the workflow looks like

Say support notices the docs describe a setting that moved two releases ago.

The support lead opens the page in specgit from the repo file list, fixes the two sentences in a visual editor, and keeps writing. Saving happens automatically, and each save is a commit on a working branch, attributed to them, with history they can undo back through. When they are done they hit publish, which opens a pull request against your default branch.

A writer or engineer reviews it. Comments left on a highlighted paragraph in specgit are real pull request review threads, so the reviewer can answer from GitHub without opening specgit at all. If your repo requires two approvals before anything lands, that rule holds: specgit shows the author what is blocking the publish, they request reviewers from the publish menu, and Publish when approved merges the moment the last approval arrives. Merging is the publish. Your CI runs, your site rebuilds, and the change is in the file's history like any other commit.

What the Git-fluent half of the team keeps

This is the part that decides whether a docs owner will allow it at all. specgit adds an editing surface on top of what you run today, without adding a second system to maintain.

Your writers keep their editors, their local previews, and their branches. Your generator keeps building from the same files. Your CI keeps running Vale, markdownlint, link checks, and anything else you have wired to pull requests, because a specgit publish is an ordinary pull request and gets checked like one. Branch protection and rulesets keep applying, since specgit merges through GitHub rather than around it. Review still happens in the pull request, so the review history stays in one place instead of splitting across two tools.

There is no import step, no sync job, and no second copy of the content to keep aligned. specgit never keeps a copy of your documents or comments; GitHub remains the source of truth, and the temporary exceptions (live collaboration state while people edit together, AI you explicitly invoke, feedback you choose to share) are spelled out on security. If you want the plumbing, how it works maps each editor action to its GitHub primitive.

What the non-Git contributor never sees

The list of things a new contributor does not have to learn before their first useful edit:

• Cloning a repository, or installing anything at all. specgit runs in the browser.
• Branches as a concept they manage. A draft is a branch, but it is presented as a draft.
• Rebasing, force pushing, or resolving a conflict at a command line. When a conflict does happen, it is resolved in the editor.
• Markdown syntax. They write in a visual editor and the file on disk stays Markdown, including Obsidian-flavored syntax like wiki links, callouts, footnotes, KaTeX math, frontmatter, and Mermaid diagrams, which render inline rather than showing up as code.
• Commit messages, pull request titles, and the GitHub review UI, unless they want them.

Getting people started without a migration

You do not have to move a docs set to test this. Send someone /try, where they can open a Markdown file from any public GitHub repository and edit it with no account and nothing installed. It is the real editor, so what they see is what they would get.

For your own repo, everyone signs in through the specgit GitHub App: fine-grained, repo-by-repo permissions with short-lived tokens, no separate password and no broad OAuth grant. An individual can install it on their own account; an organization installs once through an admin, and members can request that install in one click.

Then pick one page rather than a section. A page somebody has complained about twice is ideal, because you find out quickly whether the person who complained will fix it themselves. The Free plan covers unlimited collaborators on one repository with five publishes a month, which is enough to answer that question before anyone is asked to pay. Details on pricing.

Where this does not fit

The honest limits, because finding them after a migration is worse than reading them now.

• Markdown and HTML only. If your docs are authored in .mdx with React components, or in .rst for Sphinx, specgit cannot edit them today. Most repos never hit this: GitHub code search in July 2026 indexed roughly 24.6M .md files against roughly 0.32M .mdx, about 77 times more plain Markdown, which puts MDX near 1.3% of that pile. Where it does bite, it bites hard, because MDX concentrates in JavaScript and React documentation stacks like Docusaurus, Nextra, and Mintlify, so a dev-tool docs site whose pages carry embedded components is blocked today. Python documentation on Sphinx and .rst is out for the same reason.
• GitHub only. The whole product is built on GitHub primitives, so a repo on GitLab or Bitbucket is not something specgit can open.
• Repos where the docs are mostly binaries. A folder of PDFs, design files, or generated assets is not the target. specgit edits text files; existing Word, PowerPoint, Excel, and PDF files can be imported by converting them to Markdown, but that is a one-way conversion into the repo, not ongoing editing of the original format.
• Publishing a site. specgit does not host or render a documentation website. Whatever generator or platform you use for that keeps doing it, and the GitBook comparison covers where that line falls.

Why this is worth the setup

The payoff is that the update happens at all, and that it happens where the change pressure is. A doc that lives in the repo sits in the path of the pull request that changed the behavior, so fixing it can be part of the same review instead of a task someone remembers on Friday. The mechanism behind doc drift is mostly location, not discipline.

The second reason is AI coding agents. They work from the repository, so a spec in a doc app is not context for them and a Markdown file two directories from the code is. Whatever a support lead corrects in the docs today is what an agent reads next week.

If the people you are trying to enable are product managers specifically, this guide covers the same ground from their side. If they are coming from a doc app, Google Docs and Notion both have their own comparisons, and there is a longer argument about where specs should live.

Frequently asked questions