[Gluster-devel] Gluster Programmers' Guide
Vijay Bellur
vbellur at redhat.com
Wed Jan 8 17:03:07 UTC 2014
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
More information about the Gluster-devel
mailing list