Why I Write Specs in Markdown
In a product group recently, someone asked how everyone stores and shares requirements. Most people said Google Docs. I was surprised more people weren't already using markdown. I work with AI coding agents every day. Those agents need to read my specs, my requirements, my project documents. And the format I write them in directly affects how well the agent understands them.
If you're a product manager still documenting everything in Google Docs, Word, or PDFs, you're not doing anything wrong. But if you're starting to work with AI agents, the format of your documents matters more than you think.
The problem
The industry term for what this is: unstructured data. And it's the reason an entire category of AI tools exists just to convert documents into something machines can read.
AI coding agents don't parse traditional document formats reliably.
PDFs are digital paper. They care about where a pixel sits, not what a paragraph is. Tables that look clean on screen turn into a mess of text when extracted. Headings that provide structure get flattened.
Word docs carry hidden formatting. Styles, track changes, embedded objects. A clean-looking document on your screen is a bloated XML file underneath. A 10-word sentence can be wrapped in hundreds of lines of XML tags, which wastes the AI's context window. Convert it poorly and the agent gets garbage.
Spreadsheets are worse. A well-structured Excel file makes perfect sense to a human scrolling through cells. To an agent, it's a grid of coordinates. The relationships between cells, the meaning of merged headers, the context a human picks up instantly, all of that is lost. The merged header problem alone causes more parsing failures than any other issue with tabular data.
Slide decks are the worst offender. PowerPoint files are essentially graphic design files. There is no inherent structure for an agent to extract. The information exists, but it's buried inside visual formatting choices.
A human reads a table and sees relationships. An agent reads the same table as flattened text and loses the hierarchy. The information is there, but the structure isn't.
Markdown as the interface
Markdown is plain text with structure. Headings, lists, tables, links, code blocks. No hidden formatting, what you see is exactly what the agent gets. It's the simplest format that still carries meaning, and AI agents parse it reliably.
When your specs, requirements, and project docs are in markdown, agents can read them without mangling structure. Tables stay as tables. Headings stay as headings. The agent sees what you wrote, not a degraded version of it.
The tool
MarkItDown from Microsoft Research converts Word docs, PDFs, Excel, PowerPoint, images, and audio into clean markdown. Open source, MIT licensed, one command.
The point
Before optimizing prompts, optimize formats. The downstream output depends on the upstream input. Markdown is the format that bridges the gap between how humans write documents and how agents read them.