format will change from LaTeX -> (CommonMark|AsciiDoc): which should we chose?

Ben Cotton bcotton at
Mon Aug 15 13:07:58 EDT 2016

Having learned my documentation skills in Fedora, I'm biased toward
DocBook XML. But that's not on the list, so I won't advocate for it

I have a fair amount of experience with Markdown in various flavors
(not CommonMark specifically, AFAIK), and none with AsciiDoc, but I'd
vote for the latter rather than the former. Here's why:

* My view of Markdown and similar languages is that it lacks the
semantic richness to really do long-form materials well. I think it's
great for short, self-contained content, but not for book-like
* AsciiDoc is [apparently] becoming very popular for long-form
writing. I believe it is the preferred format for O'Reilly and perhaps
other publishers as well.

I've used LaTeX for various projects (mostly in graduate school) and
while I'm comfortable enough with it, I'd never subject anyone else to
it. :-)

My general position on documentation, though, is "write it in whatever
you want and we'll convert it to the right format." Contributions that
come in the form of patches already in the right format are easiest to
accept, of course, but the content generation is the hard part and the
part we most need from the passive contributor. I'd rather transcribe
a smartphone photo of words someone scrawled on a napkin than have no
contributions at all.

(I say this having made effectively no contributions to this project
myself, a fact I've been reminded of twice so far today. I suppose I
should get on that.)

Ben Cotton

More information about the discuss mailing list