[GNC-dev] Long Term Documentation Directions

Geert Janssens 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 
language directory.
- let gettext extract all translatable strings and offer the translator a 
message catalog to translate.

Both methods have advantages and drawbacks.
Method 1:
+ 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

Method 2:
+ 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 
the user.

- 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 
still python2.
- 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 mailing list