Obviously, the best documentation is the one that exists in the first place, and markdown is a very low-friction way to document things. That said, FWIW, using

Obviously, the best documentation is the one that exists in the first place, and markdown is a very low-friction way to document things. That said, FWIW, using markdown vs highly "semantically" structured text doesn't need to be an exclusive-or choice. Citing from sgmljs.net markdown (markdown-in-SGML): > sgmljs.net Markdown is presented as an application of the SGML SHORTREF feature, which is an SGML mechanism to describe custom Wiki or other domain-specific syntax. Whereas in regular markdown it's possible to use HTML markup, in sgmljs.net Markdown it's also possible to use SGML markup and other constructs, bringing SGML's vast facilities for text organization and processing to markdown in a natural way. [1] For example, to annotate HTML's text spans semantically with RDFa or whatever, add context-dependent CSS classes, perform transformations, define custom syntax on top of markdown, customize markdown flavours such as github's, use text macros, add page boilerplate, etc. [1]: http://sgmljs.net/docs/markdown.html http://sgmljs.net/docs/markdown.html (my site)