Docs-as-code treats documentation like source: it lives in git as Markdown, it moves through pull requests, and it ships from the same pipeline as the code it describes. It is a good model, and it has one persistent gap. The people who most need to review a spec, a PRD, or release notes are often not the people who are comfortable in a pull request. This post is about closing that gap by putting a real Google Doc in the review loop without giving up Markdown as the source of truth.
What docs-as-code gets right
Keeping documentation as Markdown in the repository buys you the things you already value in code:
- History and provenance. Every change is a commit with an author and a diff.
- Review in context. Docs change alongside the code, in the same pull request.
- One source of truth. The file in the repo is authoritative, not a copy in someone's Drive.
- Automation. The same pipeline that tests code can lint, build, and publish docs.
For an engineering audience, this works well. The friction shows up at the boundary.
Where it breaks: the reviewer boundary
A pull request is a great review surface for engineers and a wall for almost everyone else. When a product manager, a lawyer, or an executive needs to weigh in, "leave a comment on line 42 of the diff" is not a reasonable ask. So the doc gets copied out to a Google Doc for their review, and now there are two versions: the Markdown in git and the Doc people are actually commenting on. Their edits live in the Doc, your source of truth is in the repo, and reconciling the two is manual.
This is the same stale-copy problem you hit with any one-time conversion, just recurring. Exporting to Markdown or pasting into Docs both produce a snapshot that is out of date the moment either side changes. For the details of what converts and what breaks, see Google Docs Markdown: what works, what breaks.
Closing the loop with two-way sync
The fix is to make the Google Doc a live view of the Markdown rather than a copy of it. With two-way sync:
- The Markdown file stays your source of truth in the repo, with full git history.
- The Google Doc stays a genuine, native Doc, so reviewers get comments, suggestions, and the editing experience they already know.
- Changes flow in both directions, so a suggestion accepted in the Doc lands back in the Markdown, and a commit to the Markdown updates the Doc.
Nobody pastes content back and forth, and there is no second version drifting out of date. Your reviewers never have to see the repo, and you never have to leave it. This is exactly what md2gd is built to do.
How this fits an agent workflow
The same loop matters when an agent is the author. If an assistant regenerates a spec as Markdown on each run, and a human reviews it in a Doc, syncing keeps the generated Markdown and the reviewed Doc aligned instead of forcing a re-paste every iteration. The agent writes Markdown, the reviewer stays in Google Docs, and provenance stays intact on the Markdown side.
Copy-paste versus sync
| Concern | Copy-paste / export | Two-way sync |
|---|---|---|
| Source of truth | Ambiguous, two versions | The Markdown file in git |
| Reviewer experience | Comments stranded in a copy | Native Google Docs comments |
| Edits from reviewers | Reconciled by hand | Flow back to the Markdown |
| Stays current | No, snapshot goes stale | Yes, both sides track each other |
Getting started
If your immediate need is a one-time conversion in either direction, the free tools cover it: Google Doc to Markdown for exporting and Markdown to Google Docs for the reverse. If the problem is that the same document keeps moving between a repo and a reviewer, that is the sync case. See also how to convert a Google Doc to Markdown for the export side of the workflow.
FAQ
What is docs-as-code?
Docs-as-code is treating documentation like source code: writing it in Markdown, storing it in git, reviewing it in pull requests, and publishing it from the same pipeline as the code.
Why involve Google Docs at all in a docs-as-code workflow?
Because many reviewers are not comfortable commenting on a pull request. A Google Doc gives them the familiar comment-and-suggest experience while the Markdown stays authoritative in the repo.
How do reviewer edits get back into the Markdown?
With two-way sync, changes made in the Doc flow back to the Markdown file, and commits to the Markdown update the Doc, so neither side goes stale. md2gd is built for this.
Is a synced Google Doc still a normal Doc?
Yes. Sync keeps it a genuine native Google Doc with full comments and suggestions, rather than a lossy import artifact.
The takeaway
Docs-as-code is the right home for documentation, and the pull request is the wrong review surface for non-engineers. You do not have to choose. Keep the Markdown as your source of truth and let a synced Google Doc carry the review, so the loop closes itself instead of running through a copy-paste chain. Start with the free tools for one-off conversions, and reach for sync when the same document keeps crossing the boundary.
