|
From: | Vijay Bellur |
Subject: | Re: [Gluster-devel] Gluster Programmers' Guide |
Date: | Wed, 08 Jan 2014 22:33:07 +0530 |
User-agent: | Mozilla/5.0 (X11; Linux x86_64; rv:24.0) Gecko/20100101 Thunderbird/24.1.0 |
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
[Prev in Thread] | Current Thread | [Next in Thread] |