[Gluster-devel] Gluster Programmers' Guide

[Jeffrey Darcy]

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

Agreed.  DocBook failed for essentially the same reason as any binary
format would - incomprehensible format, special tools, lousy diff
behavior, generally unfriendly to collaboration.  I'd prefer *any* of
the text-based formats to that.

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

I hope not, as well.  As far as I can tell, AsciiDoc has all of the
features I could imagine being useful even for a book-length document.
I'd be comfortable writing in that.