[Gluster-devel] Gluster Programmers' Guide

[Vijay Bellur]

On 01/08/2014 09:57 PM, Jeffrey Darcy wrote:
>> 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.

Agree that there are obvious advantages with asciidoc for features that 
you mention.

>
> Saying that "we" have settled on Markdown seems a bit premature when
> parts of the project are also using AsciiDoc.

Looking back at my original post, I seem to have conveyed a sense that 
"we" have settled on Markdown but that never has been our intent. My 
response was more directed towards previous queries on whether we have a 
format for managing our documentation. markdown is a *huge* win over 
docbook and the fact that we got a few patches in markdown as opposed to 
none when it was docbook does make it look like a better choice than 
before :).

If we look at gerrit when the markdown conversion was posted or 
subsequent discussions around documentation, we have always been open to 
the idea of moving all documentation to asciidoc.

> 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.
>

Agree here.

We can possibly adhere to this model going forward:

1. Use markdown for whatever is currently in that format.

2. Use asciidoc or markdown for new documents that we evolve.

3. Have a switchover from markdown to asciidoc at some point in time so 
that we have a uniform mechanism for handling documentation.

Do we need any other formats for documentation apart from these two? I 
hope not :).

Thanks,
Vijay