Markdown Is the Worst

Markdown is the worst form of documentation, except for all those other forms that have been tried.¹

I agree with the authors of The Pragmatic Programmer: knowledge should be kept in plain text. When it’s used to document code – including infrastructure-as-code – the closer it’s stored to the code it’s documenting, the better.

Let’s say you search your code repository for fooComponent. You’ll find where it’s defined and referenced in the code, of course. Imagine if your search results could also include the documentation that explains the context around something being named as atrociously as fooComponent. This is the Tao of README.

• Plain text is easy to read using cat, less, vim, or (winces) Notepad.
• Plain text can be easily diffed by git.
• Plain text docs that are stored in source control allow changes to be tracked right alongside the code they reference, carrying all of the useful context of commit messages and pull requests with them.
• Plain text can be easily managed using 50-year-old UNIX tools that are already installed everywhere².
  • search: grep related: ripgrep (rg) may be my favorite tool.
  • edit: vim
  • analyze: wc
  • process: sort, uniq, tr, awk, sed
• Plain text can never become obsolete or illegible the way every other (binary) format can; there’s no such thing as a backward-compatibility-breaking change for plain text.
• “Open” doc formats like .docx are better than their predecessors, but they’re unreadable without tooling like zip. The HTML these apps generate is a war crime. And don’t get me started on XML.

After the climate apocalypse, as the tumbleweeds roll across the desert formerly known as Silicon Valley, if there’s any remaining documentation of use to humanity, whatever isn’t already printed might live on as plain text… that is, if there are still computers, and electricity to power them, and humans to read it. Thanks for coming to my TED talk.

AsciiDoc for TODO lists and miscellaneous writing

For years my favorite plain text doc format has been AsciiDoc. It’s a superset of Markdown that has enough features to beautifully render articles, books, HTML, slide decks, PDFs, and eBooks (ePub).

My default note-taking system is a collection of .ad files. When I occasionally want to cross-link docs or supersede them, it’s easy to do it. AsciiDoc renders nicely in Chrome using Asciidoctor.js, and it’s easy to copypaste the rendered output into an email, or I can drop to the command line to export a PDF or create a slide deck.

AsciiDoc for presentations

It’s a little cumbersome to use metadata to add basic animations to slides, and it’s not as full-featured or pretty as something like reveal.js, but it’s a nice head start toward a viable presentation if the documentation’s already in AsciiDoc.

Markdown for READMEs

I’d love to use AsciiDoc for all READMEs. GitLab and Github support automatic rendering of a README.ad at the root of a repository, but Bitbucket doesn’t without a 3rd-party app that I can’t install. I want READMEs to be automatically rendered regardless of the Git host, so README.md it is. Atlassian is why we can’t have nice things.

Markdown for ASCII output

There are a lot of free-text form fields in UIs where you can paste Markdown and have it automatically rendered upon viewing. I use Markdown output in programs that emit tables or other plain text that could benefit from formatting.

Markdown for websites

This site is written in Markdown and rendered to static files in milliseconds by Hugo. It requires no database or application hosting of any kind and essentially costs nothing to serve to readers.

To update this site, I write, commit, and git push. Netlify automatically runs Hugo and deploys the static files, which are served via HTTPS thanks to Let’s Encrypt.

Let’s Encrypt is a gift to humanity, Netlify is great, and Hugo is awesome.

Markdown for Slack

Slack’s message formatting isn’t Markdown, strictly, but it borrows from the Markdown syntax in several useful ways: bold, italics, quotes, bullet and ordered lists, single-tilde inline code, triple-tilde code blocks, etc. If you use Slack, you probably already know how to write (a subset of) Markdown.

on the subject of wikis and “rich text”

Confluence and I were in a fight, but we’re working it out. Its implementation of Markdown formatting used to be inconsistent. It’s also, still, approximately as frustrating as Microsoft Word when trying to, say, reasonably format and re-indent bullet and numbered lists, the unspoken hardest problem in computer science.

I leaned hard into Confluence once Atlassian shipped support for real-time collaborative editing. Confluence seems to occupy the space between Word Online and Google Docs: it’s not quite buggy enough to make me lose work and defenestrate my computer, but it’s not publicly-accessible enough to serve as a universal tool for both the internal and external documentation for an organization. Again, Atlassian is why we can’t have nice things, but when in Rome…

I long for a day when everyone’s comfortable enough with Markdown, AsciiDoc, and Git to use them instead of any kind of RTF or WTF™ (Wiki Text Format).

no, really, go check out AsciiDoc

You’ll be glad you did.