The Replacement ■ Episode 11
John Gruber wrote the specification in 2004. A Perl script. 1,122 lines. The design goal: "A Markdown-formatted document should be publishable as-is, as plain text."
Twenty-two years later, the format has not changed. It is text.
The Overengineered
Your documentation lives in a Jira ticket. Written in a WYSIWYG editor that mangles formatting on paste, loses indentation on save, and renders code blocks in a font suggesting the designer had never actually seen one.
Or in
Confluence.
Proprietary XML. Try exporting it. Macros become
UnknownMacroMigrationException. Marvellous.
Or on a SharePoint. Three versions behind the code. Nobody knows which is current. Everybody quietly hopes it will not matter.
The Stable Replacement
A .md file. Next to your code. In the same repository.
Versioned with the same commit. Reviewed in the same pull request.
When the code changes, the documentation changes with it. Or the
reviewer asks why it did not.
Stack Overflow Developer Survey 2024: 84% admiration score. Highest of any technology. Third consecutive year. One suspects the remaining 16% simply have not tried it.
But "it's just plain text," they say. Quite.
Not Just Plain Text
Mermaid: architecture diagrams, flowcharts, sequence diagrams. No Visio licence required. LaTeX: mathematical notation, inline. Code blocks, tables, links, images, footnotes, task lists.
None of this is native to the format, but all of it integrates seamlessly because the format is open enough to allow it.
A .md file with a Mermaid diagram is rather more useful
than a Confluence page with a screenshot of a Visio file from a
Lucidchart nobody has access to anymore.
The Machine Age
Every large language model reads Markdown. Every large language model
writes Markdown. It is, alongside JSON, the native format of the
machine age. Your Confluence page needs a plugin. Your
.md file just works.
The Tooling
Every editor renders Markdown natively. Zed, VS Code, IntelliJ, PhpStorm. It is not a feature. It is an expectation. Not supporting it would be considered a defect.
git diff shows you what changed. git blame
shows you who wrote it. git log shows you why. GitHub,
GitLab, Codeberg render it beautifully in the repository. Your Jira
ticket shows you a wall of rich text and hopes for the best.
The Point
Documentation belongs next to the code. In a format that every tool reads, every developer writes, and no vendor controls.
It is a text file. It always was.