April 3, 2026

Internal Git, PDF Handouts — Doc Workflow for PMs & Engineers

Git-based doc workflow for PMs and engineers: branch → PR review → tag → PDF export. Covers folder structure, version naming, confidentiality handling, and a pre-release checklist.

Audience and context

This article assumes teams where:

Product managers need to explain which spec version is official as scope and priorities change.
Engineering managers / tech leads want reviewable design and operational history.
Individual contributors want API specs, error catalogs, and runbooks easy to tie back to issues and PRs.

The shared pain is: Git works internally, but customers, sales, legal, and other departments often expect PDFs. Below is a practical way to bridge that gap.

Why split “Git” and “PDF” (by role)

Perspective	Git (Markdown)	PDF (handout)
PM	History and diffs explain what changed when	Contracts and approvals need a pinned version
Engineering	Fits PRs and branching	Print, offline reading, stable layout
External stakeholders	Often need Git access and literacy	Attachments everyone can open

Mixing “authoring” and “slide-grade layout” in one Markdown file often bloats the source and hides the real diff in review. Keep authoring and history in Git, and treat PDF as the distribution surface.

Doc types and folders

Reduce “where is the spec?” debates by folder conventions:

Product / API specs → docs/spec/, docs/api/ (read per release).
ADRs → docs/adr/ (short decision records).
Runbooks → docs/runbooks/ (incidents, release steps).
Customer-facing commitments → tighten versioning: e.g. PDF only from tagged commits.

A single docs/README can work early; as the team grows, split folders by meaning so both PMs and engineers can discover content.

Lifecycle: draft → review → approval → tag → PDF

A simple shared rhythm:

Draft on a feature or docs branch.
Review in a PR; link issues/tickets to spec changes.
Approve per team rules, then merge.
Tag when you release or need a customer-visible snapshot (e.g. docs-v2.1).
PDF from that tag’s Markdown and attach to release notes or a canonical share location.

You don’t need a new PDF on every commit—cut PDFs when “this version is official.”

What helps PMs

Map milestones to docs: which chapters/issues match “frozen for this sprint.”
Make scope changes visible: one line in the PR description on why the business context changed (helps audits and retros).
Pair customer promises with versions: record PDF filename + Git tag in release notes (e.g. “official PDF spec-v2.1.pdf at tag docs-v2.1”).

What helps engineers

Size PRs like code changes: reviewable chunks.
CODEOWNERS for docs/api/ vs docs/runbooks/ so the right reviewers are pinged.
Link issues and ADRs so “why we decided this” survives.

Some teams auto-build PDFs in CI; “tag, then export PDF in the browser” is fine to start. Automate after the doc process stabilizes.

PDF naming and storage

Filenames: include the version, e.g. api-spec-v2.1.pdf.
Single source of truth for links: release notes, internal wiki, or customer portal—one canonical place for “the official PDF.”
Tie back to Git: note “source at tag docs-v2.1” in README or release notes so PDF and Markdown don’t silently diverge.

Why browser-based PDF export matters

For customer names, unreleased features, or PII, you may not want to upload body text to a hosted converter. Loading Markdown in the browser, checking preview/layout, then Save as PDF can be built so files are not sent to a server (this site follows that model).

Formal security review is also easier when the toolchain stays local to the browser.

When it goes wrong

Situation	What to do
Too many PDFs; unclear latest	Always point to the official PDF from tags / release notes
PDF and Markdown drift	Generate PDFs only from tagged commits
PM vs engineering mismatch	Agree in PR; customer PDFs only after merge
Stakeholders who don’t use Git	Draft anywhere; pin the final PDF + tag

Pre-release checklist (example)

Before sending a PDF externally, template a checklist like:

Markdown is merged to main (or the release branch).
A Git tag exists and is named in release notes.
The PDF filename includes the version.
Legal/sales sign-off if required.
For sensitive content, generation follows browser-only / internal policy.

Summary

Git (Markdown) for diffs and review; PDF for pinned distribution.
PMs own milestones, scope communication, and “official version” clarity; engineers support with PRs, CODEOWNERS, and issue links.
Prevent drift with tags + PDF naming + release notes.
For confidentiality, add in-browser PDF export to your options.

For UI steps, see How to Convert Markdown to HTML and PDF — Step-by-Step Guide. For page breaks, see How to Control Page Breaks in Markdown PDF.

Open the tool to export PDF