Why Word in Git is a footgun

Git stores .docx files as opaque binaries. git diff README.docx shows "Binary files differ" — useless. Two collaborators editing the same .docx produce a merge conflict Git cannot resolve, requiring manual reconciliation in Word with all the friction that implies. Code review on a Word document means downloading the file and eyeballing it, with no inline comment support.

The same content as Markdown solves all three problems. Diffs are line-by-line. Merge conflicts are conflict markers any text editor can resolve. PRs render the diff inline; reviewers leave comments on specific lines; CI can lint the prose with vale or similar tools. Documentation finally becomes part of the engineering workflow.

The migration workflow

Convert each Word document on Word to Markdown, commit the .md to docs/ in the repo. Update README.md to link to the new doc paths. For Wiki content, GitHub Wikis are themselves Markdown — paste the converted content directly into wiki pages.

For multi-source documentation: pair with PDF for GitHub, URL for GitHub, Audio for GitHub, and Video for GitHub. Every documentation modality lives in the repo as version-controlled Markdown.

For mass-migration of legacy doc archives

The web tool converts one document at a time — fine for a few key docs. For hundreds of legacy Word files at once, run Pandoc locally in a shell loop (for f in *.docx; do pandoc "$f" -o "${f%.docx}.md"; done), then commit the resulting .md tree in one PR. Honest tradeoff: web tool for ad-hoc, OSS for batch.