Twelve years ago, I built a little Heroku app to convert Microsoft Word documents to Markdown, because government employees kept asking me for one. It now lives at word2md.com, and these days it’s busier than it has ever been. I’d bet most of the people using it aren’t developers. They’re people with a folder full of .docx files who’ve noticed their chatbot gives better answers when they paste in plain text.
They’ve figured out something I wrote about in Open and Async:
Teams with well-structured, up-to-date documentation get noticeably better AI-assisted answers because the model can find relevant context. Teams with scattered tribal knowledge get generic responses. Your documentation quality is your AI quality now.
That’s a writing problem, and it was a writing problem long before the model showed up.
Markdown is the cheapest fix I know, for the reason I gave back in 2014: it makes you write for the reader you actually have. In 2014, that reader was a browser. Now it’s often a model summarizing your proposal before your boss skims it.
Structure is what the model sees
Word processors encourage you to describe what something looks like. Markup makes you declare what it is. In Markdown, ## Deprecating the v1 API says “this is a second-level heading.” Word can say the same thing with its Heading 2 style, but it also lets you just make the text big and bold, and most people do. The two look identical to a sighted reader. A screen reader or a language model sees a plain paragraph.1
As I put it in the book, markup is a contract; formatting is a costume.
To see the difference, I built the same short vacation policy twice: once with Word’s heading and list styles, and once formatted by hand, with a bold 14-point heading and typed step numbers. Then I ran both through word2md.2 The styled version came out as:
## Vacation policy
To request time off:
1. Tell your manager.
2. Add it to the team calendar.
The hand-formatted version came out as:
**Vacation policy**
To request time off:
1\. Tell your manager.
2\. Add it to the team calendar.
Same words, same look on screen. The first has a section a model can find and a list it can count. The second has a bold sentence and two paragraphs that happen to start with numbers (the backslash means “not a list”). No converter can recover structure the author never declared. Try it on one of your own documents: drop it into word2md.com and look for bold lines that should have been headings.
Tables fare even worse. When I ran the same file through macOS’s built-in plain-text converter (textutil -convert txt), the three-column table of accrual rates came out as twelve lines, one cell per line: Tenure, Days per year, Carryover, 0–2 years, 15, 5, and so on. Nothing ties the 15 to its column. Chatbots use better converters than that, but you can’t see what yours kept, and you won’t know until the summary comes back wrong.
Word files are tiny jails for content
A .docx is a zipped bundle of XML built for one application to reopen. The book puts it more bluntly:
Word processing documents are tiny jails for content. Proprietary formats blend text with the commands the software needs to recreate it, in formats built for the application rather than the reader. We put in text, one of the simplest things computers understand, and get back a mess that only specific software can open. It’s like keeping every grocery list inside a screenshot of an Instagram post: the words are there, but only one tool can read them, and you can’t edit so much as a typo without retaking the picture.
In 2014, I measured the same sample both ways: 33,621 bytes as Word, 80 as Markdown.3 Your chatbot throws most of that away before the model ever sees it, and every trip out of the jail is a chance to lose structure, the way that table lost its columns. A smaller file won’t fix that. A format where the structure is the text will.
- Getting content in. word2md.com converts Word documents to clean Markdown, entirely in your browser, so the file never leaves your computer.
- Getting content out. md2word.app goes the other way. Your AI assistant drafted the policy in Markdown, but legal wants a Word file they can redline.4 md2word builds one, also in your browser.5
Markdown is where you and your AI tools do the work. Word is a delivery format you add at the last possible moment, for the people who need it.
A playbook for AI-ready docs
You don’t need a migration project.
For everyone
- Use real headings. In Word or Google Docs, that’s the Heading 1, 2, and 3 styles, not bold text. In Markdown, it’s
##. - Use real lists. Click the list button instead of typing numbers or dashes by hand.
- Write headings that promise something. “Background” tells a reader (or a model searching for an answer) nothing. “Deprecating the v1 API” tells them exactly what follows.
- Keep one living copy and share a link. One Google Doc or wiki page beats five attachments in five inboxes. If you can’t tell which version is current, neither can your AI tools. At GitHub, even the vacation policy worked this way (non-technical teams can too).
- Convert legacy docs once, then stop editing the Word version. Run the important ones through word2md.com, check the output, and make that (or a properly styled Google Doc) the canonical copy.
- Export to Word only at the end. When someone needs a
.docx, generate it with md2word.app. Treat it like a printout: disposable, and never the source of truth. - Don’t wait for permission. Draft your next proposal with real structure, keep it somewhere with version history, and share a link instead of an attachment. When your reviews move faster, people will ask how.
If you’re technical
- Put your Markdown in version control. Every change becomes a diff you can review.
- Keep your AI instructions in Markdown, too.
AGENTS.mdandCLAUDE.mdare just Markdown in your repository. This blog has both. - Let your agent do the converting. Both tools are also MCP servers (listed in the registry), so Claude, Copilot, or whatever agent you use can turn a
.docxinto Markdown (and back) without you opening a browser tab. Or runnpx word-to-markdown input.docxandnpx markdown-to-word input.mdyourself.
Write for the reader you have
The government employees who asked me for that Heroku app wanted their documents on the web. The people using it today want their documents in a chatbot. Different reader, same problem: the structure was never in the file, and no tool can put it back.
Markdown has bet on structure over formatting for more than twenty years. Stop doing your thinking in Word. Do it somewhere a screen reader, a model, and the new hire can all tell what you meant.
-
That’s also why my ebook turned out to be accessible by default. Screen readers and LLMs want the same thing. ↩︎
-
If you want the real thing rather than a two-step demo, the book’s appendix includes a complete time-off guide written this way. ↩︎
-
That’s about 420 times the bytes (33,621 ÷ 80), which overstates it: most of a
.docxis fixed overhead that doesn’t grow with the document. Bytes aren’t tokens, but even the HTML version, a fairer comparison, was about 17 times the Markdown (1,359 ÷ 80). ↩︎ -
The round trip isn’t lossless. When legal sends the redline back, word2md drops the comments and silently accepts every tracked change. Resolve both in Word first, then convert the clean copy and compare it against your source. ↩︎
-
Both are open source and available in 21 languages. word2md is a 2024 rewrite of that original Heroku app (source on GitHub), and I built md2word this year (source on GitHub). ↩︎