Using AsciiDoc for Documentation

[Geert Janssens]

On Wednesday 02 September 2015 22:06:30 David T. wrote:
> 
> John,
> 
> I’ve looked at the documentation a little. It looks a lot like the
> wiki syntax. I personally don’t feel strongly about one format over
> another, except inasmuch as I have already spent a good bit of time
> learning the current documentation syntax.
> 
> Frankly, for me the problem has never been whether the documentation
> uses one obscure text-formatting format or another. I’ve been editing
> HTML code and any of a multitude of other text markup languages in
> text editors for decades. I just look at what’s already there, and
> copy it until I eventually get it learned.
> 
> I will admit that as I age, I get less happy with the mental overhead
> of trying to imagine what things will ultimately look like—and I
> would hazard a guess that the language in the documents suffers
> because people have to spend mental cycles filtering out markup and
> imagining how things will look, rather than on what is actually being
> said. So, having a WYSIWIG editor would benefit the docs, I believe.
> 
I almost agree.

The use of the term "look like" is key. As you no doubt know the focus of xml and its variants 
such as html focus on structure and defer the visual representation to css. So what the 
document "looks like" should not be the concern. Instead how it is structured should be. This is a 
subtle but important difference.

I recently learned the term "WYSIWYM", which stands for "What You See Is What You Mean". And 
I would much rather find a good WYSIWYM editor for our documentation than a WYSIWYG one.

The problem with pure WYSIWYG editors is that less experienced people typically tend to focus 
more on the visual appearance than on the structure of the document. A simple example: you 
could mimic a heading by setting the font size and bold-face manually, but that's structurally 
not a heading and hence won't show up in automatically generated table of contents.

WYSIWYM is close to WYSIWYG but will put the focus on document structure. The structure is 
visually represented similar to WYSIWYG to make it easier to follow as a normal human being 
what you are editing.

> Ultimately, though, the problem for me with updating GnuCash
> documentation has always been about the workflow surrounding the
> actual editing. [I am reasonably sure that the developer list and
> those who must suffer with my mangling of the update/patching process
> would agree with my self-assessment.] The use of version control
> platforms for this aspect of the project may yield benefits to the
> developer base, but feels like an intense over-engineering—especially
> given the level of activity associated with the documentation (which
> is exceedingly low). I mean, if there actually were a group of even 4
> people actively working on documentation in any given month, I would
> be surprised. Given this reality, is it REALLY necessary to use
> industrial version control on two (admittedly somewhat complex)
> documents?
> 
I still think we do need some form of change management. For starters it's not just two 
documents. It's two documents translated in many languages, and maintained for two different 
versions of the program.

Without rigorous version control it becomes much harder to track the changes in the main 
document. Which parts have recently been modified that need translation still ? Which recent 
changes should also be applied to the documentation matching the development version 
gnucash ?

My experience shows this quickly gets a mess without some decent version management. The 
amount of people working on this is less relevant. Even a single user project with so many 
interdependent documents is easier to track via some form of change management.

I understand this feels like overhead. I understand git is confusing to people first introduced to 
it. I know from experience *any* change management system has this effect, because it forces 
people to think in terms of, well, "manageable changes". I'm sorry I don't know how to lower 
this barrier to entry.


> I am reminded of the MIDI music studio I had in the early 90s. At
> first, I enjoyed sitting down and improvising with sounds and notes
> with a single keyboard and amplifier. Then I decided to add a nifty
> cool sampler, a digital delay, a computer, and some other gadgets,
> and it got so complicated to get everything up and running that I
> would lose whatever musical inspiration induced me to turn it all on
> in the first place. I ended up getting an acoustic piano.
> 
> The GnuCash documentation update process is like this, with all the
> protocols around bugs and git, and xmllint-ing and xslt-ing before
> formatting an appropriate patch (and watch out that you don’t
> accidentally push a patch [or is that pick a peck?] that can’t be
> parsed). It’s a wonder that any of us writerly and not developer-ly
> types get through any of it.

Let me point out that the xmllint-ing and xslt-ing you are referring to is the direct result of not 
having a decent WYSIWYM editor for docbook. That means manually typed text needs semantic 
validation. This has nothing to do with the change management overhead. Hopefully we can 
overcome this with an alternative as we are once more discussing here.

The patch submission burden is still there indeed.

I'm grateful for your perseverance and appreciate your input in this conversation.

For me your view is a confirmation of Christian Stimmings original assessment from a couple of 
years back. Simply switching to asciidoc will probably not solve the issue. There's no true 
WYSIWYM editor for it, so a semantic validation will still be needed (similar to xmllint). The 
editors with live preview do help, but in the end it's still distracting from content towards writing 
code to structure the document. To be fair I do think though that asciidoc will be much easier to 
do right than docbook is so it still could be step in the right direction.

Regards,

Geert