If there is any one aspect of software projects that is skimped on most often, it’s documentation. Undocumented software is, in the long run, unusable software. Problem is, writing software documentation can be tedious work, especially when there is elaborate formatting involved: tables of contents, footnotes, end-notes, hyperlinks, and so on.
Once upon a time, the typical way to document your project was to author HTML. But a better way emerged: Use textual formats that are easy to read in their raw form, but can be quickly rendered to produce sophisticated markup.
Several different text formats have evolved to fill this need—some from the blogging community, others from more formal software development circles. Here, we’ll look at the four most common formats, their pros and cons, and the kinds of projects they’re best suited for.
Markdown
Developed by John Gruber in 2004, Markdown was originally created for blogging—to provide a way to quickly add common formatting to plain text documents without using friable inline HTML. The idea was that the original document, with its annotations, should be readable as text, but also provide visual cues to allow the reader to grasp the structure of the document at a glance.
