[GNC-dev] Help documentation

[John Ralls]

The way we manage program help has four serious problems:

1. It's separate from the program--not even in the same git repository--so changes to the program are seldom reflected in the help. Very little of it has been touched in the last 10 years.

2. It's largely monolithic which makes it resistant to translation, so while the program is translated into 58 languages, the help has only 3, only 1 of which, German, is up to date.

3. It's formatted with Docbook, an XML dialect with no usable editing or translation tools, so authors and translators must learn to edit XML by hand and learn to work the document build system so that they can build to HTML and then review their work in their browser. Pretty damn tedious.

4. A lot of GnuCash is completely undocumented.

Note that unlike the Tutorial and Context Guide sections of the help are reachable by context help buttons throughout the UI. ISTM that should make it more amenable to translation with gettext.

I think that if the help documentation was kept close to the UI code that it would be both easier for developers to keep it in sync with code changes and for code reviewers to insist that they do so. Integrating it with the build system that they already use routinely would remove a bit of the tedium, but even better would be finding a format for which a Free WYSIWYG editor is available or better still where contributors could edit directly on Github and create a PR using the fairly simple Github online UI, making editing accessible to non-developers (that would suggest that the format should be either Github-flavored markdown or restructured text, the formats for which Github supports WYSIWYG editing).

A somewhat geekier alternative--though still far more accessible than Docbook in a separate repo--is Doxygen markup. We already use that extensively for the API (though not extensively enough, there's a lot of undocumented API). Unfortunately Doxygen doesn't provide a way to extract msgids so we'd have to either build in a format that xgettext understands or extend Doxygen.

Regardless of the markup style we need to work out exactly where in the source tree to locate the help strings and how to connect them to their respective help buttons. 

Regards,
John Ralls