A complex topic is brought up here.
I agree with the issues you bring up. I don't know if or how we can solve them
all.
In the gnucash project we currently only have experience with docbook for user
oriented documentation and doxygen for our api documentation.
On the premise what we have so far is too complicated, I started looking at a
few other projects to figure out how they manage their help. The hope is
someone else has already solved this problem. I have only looked at a couple
of projects so far.
It may be disappointing that many of the mature projects out there have a
similar setup as we do (gimp, kontact, ...) Probably not surprising
considering these projects are around for a long time and options were limited
back in the days.
But there are a few alternative approaches:
* Libreoffice unsurprisingly handles user documentation in libreoffice
documents [1]. It is however not clear whether that also comprises their help
documentation.
They have set up a collaborative platform via nextcloud (which ships with a
collaborative word processor, akin to Microsoft's 365 office or Google's
Docs). I don't have an account there so I can't evaluate how that works
exactly.
An addition they use weblate for string translations [2]. That's a selfhosted
weblate instance, and it has a help project next to their ui project. Looking
at the source files referenced there, the strings are extracted from xhp
files. I don't know exactly what those are (yet).
So far I haven't discovered yet how much developer skills a documentation or
help contributor needs (versioning system, build recipes,...)
* Firefox has another strategy [3]. Their help system is based on reStructured
text files that sit next to the functionality. The documentation build system
picks them up from there for further processing. Again it's not clear whether
help is treated differently from guides and manuals.
Adding documentation does require tweaking build scripts (updating variables
and running builds to verify the new docs).
Their devel documentation has a large section on localization, but it's
focused on UI localization. So far I haven't found how they localize their
help.
That's what I have found so far. Curiously it seems help is always treated as
a second class citizen. While it's there, it's hard to find how it's managed.
This is meant as a starting point for further research. Others are invited and
strongly encouraged to add more references or details.
Regards,
Geert
[1] https://wiki.documentfoundation.org/Documentation/DocumentationTeamInfo
[2] https://translations.documentfoundation.org/
[3]
https://firefox-source-docs.mozilla.org/tools/moztreedocs/adding-documentation.html
Op dinsdag 16 februari 2021 18:21:03 CET schreef 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
>
