A Square Peg

Please don’t write your documentation in Markdown got a lot of attention last month, when Hillel Wayne said something both reasonable and familiar: Markdown’s simple syntax does not lend itself to complex technical documents. Antonio Zolotukhin made a similar point back in 2018, as others have before him, and more will in the future. Their argument makes sense; the idea that this is 1) a problem, and 2) needs addressing, however, does not.

Markdown supports only the most basic decorations: flags for bold and italic text, unformatted code blocks, lists, and the like. Few would want to read page after page of this plain, black and white text, but pointing to its raw form as evidence of Markdown’s unsuitability ignores the fact that no one does this anyway.

Hillel Wayne, Antonio Zolotukhin, and many others have zeroed in on a problem that does not exist.

I have used Markdown for almost a decade, in over a thousand posts for this website alone. First Crack turns that boring text into this much less boring website. People like Dave Jarvis built tools to typeset entire books written in Markdown, and other developers find interesting uses for it every day. Jeff Geerling, who refuted the idea that this syntax constrains productive work, has written thousands of blog posts and entire books with it.

Authors will continue to use Markdown for articles, books, and projects not because they have some misguided affinity for the standard, but precisely because of its simplicity. It takes care of basic text formatting, the boring majority of their work, in a lightweight and portable manner conducive to add-ons that enable the interesting, compelling aspects of it. Markdown’s detractors do not need a more robust Markdown spec, they need to use it properly.