[Gluster-devel] Gluster Programmers' Guide
Jeffrey Darcy
jdarcy at redhat.com
Wed Jan 8 18:16:10 UTC 2014
> 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.
More information about the Gluster-devel
mailing list