[GNC-dev] Long Term Documentation Directions
geert.gnucash at kobaltwit.be
Mon Sep 10 07:46:59 EDT 2018
Op zondag 9 september 2018 12:21:08 CEST schreef Frank H. Ellenberger:
> -: I18N: We will loose the current translations and probably frustrate
> the last translators and loose their readers.
Absolutely true. However I don't know if that's sufficient reason to keep the
less that satisfactory status quo.
To be honest I think this is a weakness in our tooling and one that is
preventing us from moving forward.
> ?: Usability: Will F1 or pressing the Help button still deliver the
> right content? I know it is aslo now not always th case.
If I read David's proposal carefully there remains some kind of interface
index document (listing all ui buttons, menu items,...). But instead of having
full documentation they would point to relevant sections in the manual.
Assuming we can make cross-linking work, this should be covered.
On the other hand if we think of our documentation more as a clever
composition of documentation snippets, we could also opt to compose help
information from the same snippets that are used to compose the full manual.
That's theory of course. I don't know if this would be possible in practice.
> Historical note: we had a GUM in version 1 and I assume there were
> reasons to break it in two parts.
> > We should resolve the source-format question
> > (Docbook/Asciidoc/Docx/Markdown) before beginning actual writing.
Yes, we should (the list of flavors is endless by the way, I just ran into
reStructuredText, yet another variation on the theme).
And even before that we should think in more detail on how to organize our
documentation. What structure can we come up with that works for all
contributors ? How to keep it manageable ? How to make it easy to use ?
I understand direct interaction with git is a hurdle for documentation
contributors. I still don't have a good enough alternative so far.
And then back to translations. We have experimented with two methods so far:
- each translator manually copies files from the English documentation,
directly translates that file itself and commits the result the the proper
- let gettext extract all translatable strings and offer the translator a
message catalog to translate.
Both methods have advantages and drawbacks.
+ users will only get content in their language
- however that may be very incomplete (only the parts of the manual that are
translated are presented to the user)
- it is very difficult for translators to update existing translations because
it's hard to determine what has changed in the English language
+ will always provide the full documentation to the user
- large parts can be in English instead of their native language.
- documentation updates in the English language directly affect the translated
document. For example if a paragraph has been translated and someone adds a
comma in the the English version of the paragraph, the translated
documentation will now show the English version instead of the native one.
+ this pickiness does help translators to easily spot which translations need
The question is, which is worse ? From a translator's point of view I would
think the second method would be more maintainable. However how do non-native-
English users perceive a document with mixed languages ?
Again I think better tooling can help here as well. A few examples
- when composing/building the final document in method 2 we could temporarily
remove "fuzzy" markers so that "almost good" translations are still shown to
- again for method 2 we could annotate all improperly translated sections such
that the final document has "Missing Translation" tags and a pointer to invite
readers to contribute translations.
- or even better: the online documentation should be "live" editable. The
infamous "Edit me on github" ribbons we see appear everywhere, but then
better. Ideally a mixture between something like the Edit me... thing and
something like Pootle's online translation editor:
oh and Pootle does come with git integration. Unfortunately still in beta. And
- pootle can be very useful on the translation side of things, but it's not
helping with writing documentation itself. So while searching yet again for a
possible solution I came across https://edit.php.net/ which is an online
editor for the php documentation, which also happens to be writting in
docbook. It's based on a few other projects such as https://codemirror.net/ an
online text editor for lots of languages including markdown, reStructuredText
and xml. I suspect the php team combined this with a few other bits to make it
a docbook parser with helpful elements such as an acronym browser and an
entity browser, syntax checking,...
- In the same category there are other online editors such as
* https://dillinger.io/ (Markdown, github aware)
* https://stackedit.io/ (Markdown, github aware, emoji's ! ;p )
- Of course an online editor is not *mandatory*. We would still accept direct
PR's so anyone can use their preferred editor. But my hope is that with an
online editor we could reduce the direct git interactions.
Oh, and I don't think we should *start* with an online editor. There's enough
change going on already. However while deciding our future document format it
would be nice to consider one so we don't block ourselves upfront.
Documentation updates may be a circular nightmare, finding a way to manage it
makes us running in circles as well...
More information about the gnucash-devel