RFC: Source-markup language for GHC User's Guide

[Herbert Valerio Riedel]

On 2014-10-08 at 10:49:33 +0200, Jan Stolarek wrote:
>> Therefore I'd like to hear your opinion on migrating away from the
>> current Docbook XML markup to some other similarly expressive but yet
>> more lightweight markup documentation system such as Asciidoc[1] or
>> ReST/Sphinx[2].

> My opinion is that I don't really care. I only edit the User Guide
> once every couple of months or so. I don't have problems with Docbook
> but if others want something else I can adjust.

I'd argue, that casual contributions may benefit significantly from
switching to a more human-friendly markup, as my theory is that it's
much easier to pick-up a syntax that's much closer to plain-text rather
than a fully-fledged Docbook XML. With a closer-to-plain-text syntax you
can more easily focus on the content you want to write rather than being
distracted by the incidental complexity of writing low-level XML markup.

Or put differently, I believe or rather hope this may lower the
barrier-to-entry for casual User's Guide contributions.


Fwiw, I stumbled over the slide-deck (obviously dogfooded in Asciidoc)

  http://mojavelinux.github.io/decks/discover-zen-writing-asciidoc/cojugs201305/index.html

which tries to make the point that Asciidoc helps you focus more on
writing content rather than fighting with the markup, including a
comparision of the conciseness of a chosen example of Asciidoc vs. the
resulting Docbook XML it is converted into.


Cheers,
  hvr