Markdown is an excellent choice for documentation

Every few months, it seems a new post decrying the use of markdown for documentation (or other things) rises to the top of Hacker News.

There are often good reasons for preferring a more structured option, like reStructuredText, LaTeX, or Asciidoc. Especially in projects where more formal text is required, or where you need to support specialized and structured text formatting.

But for 98% of software projects (and in my experience, 95% of all other text I've ever written), markdown suffices, and it is truly a low barrier compared to the alternatives. It's basically plain text (which anyone can learn to write in a few seconds) with extra features.

I've written two books entirely in markdown—specifically, LeanPub-flavored markdown—and besides plain text, it is the easiest language for general content authoring.

Subscribe to RSS - markdown