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 updating 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: http://docs.translatehouse.org/projects/pootle/en/stable-2.8.x/features/ index.html#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... Geert _______________________________________________ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
