[Gluster-devel] Gluster Programmers' Guide

[Jeffrey Darcy]

> We have already selected markdown as the documentation system for
> GlusterFS. markdown is not very different from asciidoc and the last
> time I checked pandoc would not consider asciidoc as input and hence
> moved to markdown.

I love Markdown, which I use for my blog.  On the other hand, for a
longer document I'd prefer a richer format.  Looking at the .md files
in the admin guide, I was immediately struck by how unreadable they
are e.g. because of manually formatted tables.  AsciiDoc seems to have
real table support, plus other things like footnotes, sidebars,
thumbnails, header/footer includes, repleaceable macros, etc.  Those
sorts of higher-level features make editing and collaboration a lot
easier than the kind of manual formatting necessary with Markdown.
It also appears that AsciiDoc converts trivially into DocBook, which
pandoc does accept.

Saying that "we" have settled on Markdown seems a bit premature when
parts of the project are also using AsciiDoc.  For developer docs it's
a particularly weak argument, since the largest document there is my
own translator guide converted from HTML and the second longest is a
coding standard converted from TeX.  There's not enough of a precedent
here to override other concerns.  A format that makes it easier to
create the initial content matters more.  So does a format that makes
it easier to update that content in ways we can predict, such as using
macros to mark recently changed API details.  For all its strengths, I
don't see Markdown as that kind of format.