Amending and enhancing the help files

l10n
#1

Hi all,

It is a secret for nobody that the help is a nightmare to maintain for
developers and contributors. However it's an important part for the
quality of our product and we need to find a way that is acceptable for
all of us working on it.

During the last Hackfest in Paris, I discussed with Moggi and Kendy how
we could organize the workflow to enhance and maintain the help and keep
the translation easy for l10n team.

So here is a proposal to discuss about using the wikihelp to maintain it:
- the existing translations would be migrated, so no work is lost (one
of the most important requirement :slight_smile:

- the translation project is split in 3 parts:
* UI as we have it today
* Extended tooltips - currently in help files, are extracted and get its
own .po project
* Help content, managed in the wiki

- review of the added/modified part on the wiki:
* random people can contribute but *not* directly
* there will be an approval process, like in Pootle or Git

- there is one point that is not optimal, because wiki syntax is
difficult to manipulate via .po files, it would be much safer to use
media wiki to translate, with the help of the translate toolkit (where
you have context, extended syntax, memories).
Note: translating via .po still would be possible, but really at own
risks.
The disadvantage that it has too is that we need two tools:
- Pootle for UI + extended tooltips,
- mediawiki for help.

So, this is how we can present the pros and cons maintaining our help
files via the wiki to reach more contributors and quality. Nothing is
set yet, but we need to find a consensus to have our help amended and
maintained, reach a good quality and really serves our users.

Feedback and ideas welcome :slight_smile:
Cheers
Sophie

#2

Hello Sophie

Thanks for bringing this issue to a broader audience. Some notes here.

Please bear in mind that not everywhere in the world have 100MB
broadband access like in Europe, and a offline help is important. That
is a constrain to having a wikihelp only solution.

Are you going to make English as the text reference to translate or each
NL team will have its own text?

Also, do we have a tool that can track each modification in the english
help file and present it for translation to our own language?

Since I played a bit with the new UI dialogs and the help files, I think
the help tips can be migrated to the *.ui files. If affirmative, it will
help to collect all related matters (ui + help tips) in the same dialog
file.

Finally, I would like to inform to the list that I opened a meta-bug to
collect the features that have no help page for.
https://bugs.freedesktop.org/show_bug.cgi?id=80430
and there is a lot of undocumented features...

Kind regards

Olivier

#3

Hi Olivier,

Hello Sophie

Thanks for bringing this issue to a broader audience. Some notes here.

Please bear in mind that not everywhere in the world have 100MB
broadband access like in Europe, and a offline help is important. That
is a constrain to having a wikihelp only solution.

It will be available as off line solution too. Even in Europe, lot of
users in companies are not able to browse online during their work time.

Are you going to make English as the text reference to translate or each
NL team will have its own text?

No, English as a reference as usual, we want to keep the same quality
for all.

Also, do we have a tool that can track each modification in the english
help file and present it for translation to our own language?

I don't know what the wiki is able to do on that matter, thanks for
pointing it. Moggi, Kendy, any ideas?

Since I played a bit with the new UI dialogs and the help files, I think
the help tips can be migrated to the *.ui files. If affirmative, it will
help to collect all related matters (ui + help tips) in the same dialog
file.

ah, interesting, thanks for the feedback

Finally, I would like to inform to the list that I opened a meta-bug to
collect the features that have no help page for.
https://bugs.freedesktop.org/show_bug.cgi?id=80430
and there is a lot of undocumented features...

I'll find some time to consolidate with the others issues that are
already opened.

Cheers
Sophie

#4

I believe the 'Translate' extension can do that:
https://www.mediawiki.org/wiki/Extension:Translate
https://www.mediawiki.org/wiki/File:Translate_manual_-Translate_example-_01._LanguageStats_long.png

If there's a way to implement a review system before proposed
translations go live, then perhaps the work could take place right in
the wiki.

I believe a few of us have suggested that we use the same extension
for translation in the TDF wiki. Perhaps we could trial it there
first?

--R

#5

Hi all,

Hi Sophie, Olivier,

Sophie píše v Út 01. 07. 2014 v 14:23 +0200:

Also, do we have a tool that can track each modification in the english
help file and present it for translation to our own language?

I don't know what the wiki is able to do on that matter, thanks for
pointing it. Moggi, Kendy, any ideas?

From what I can see, this should be possible; please see

http://www.mediawiki.org/wiki/Help:Extension:Translate

There in the picture with the "The translation editor: a message with a
tip (not visible in image) and suggestions from two assistant languages"
description, you can see a link "Show differences" next to the "This
translation may need to be updated".

Thanks Kendy. I've begin to read through the documentation of the
Translation extension. I found this page may help to understand the process:
http://www.mediawiki.org/wiki/Help:Extension:Translate/Page_translation_administration

Interesting also that it's possible to work on the source page multiple
times before tagging it for translation, and only the translation admin
could mark it.
I'll go on with the reading and report if I see something that could be
a problem for us.

Cheers
Sophie

#6

Hi all,

Also, do we have a tool that can track each modification in the english
help file and present it for translation to our own language?

I don't know what the wiki is able to do on that matter, thanks for
pointing it. Moggi, Kendy, any ideas?

I believe the 'Translate' extension can do that:
https://www.mediawiki.org/wiki/Extension:Translate
https://www.mediawiki.org/wiki/File:Translate_manual_-Translate_example-_01._LanguageStats_long.png

This shows only statistics of translations, but I've found an extension
where the translator is notified of the modifications by the manager:
http://www.mediawiki.org/wiki/Extension:TranslationNotifications

If there's a way to implement a review system before proposed
translations go live, then perhaps the work could take place right in
the wiki.

I believe a few of us have suggested that we use the same extension
for translation in the TDF wiki. Perhaps we could trial it there
first?

Because of the specificities of the work, I would prefer to have a
dedicated area for the help files test. There is a complex chain from
extracting to import/export because it's not only a wiki thing :slight_smile: I
would like to see also how off line translation looks like, etc.

Cheers
Sophie

#7

Hi,

we need definitely to go this way, so this activity is highly appreciated.

I would add one more point: currently, a lot of extended tooltips (maybe
most of them) are directly part of the help text. Therefore, if we excluded
the tips, we would have strings doubled, once in help and once in tips -
and it makes no sense to manage and translate them separately.

Together with technical solution, I think we should also have a general
discussion about help and how it should look like: for instance, do we want
pictures and screenshots in it? Or any example files, external links...
etc. etc.

Best regards,
Stanislav

#8

Hi,

we need definitely to go this way, so this activity is highly appreciated.

Thanks!

I would add one more point: currently, a lot of extended tooltips (maybe
most of them) are directly part of the help text. Therefore, if we excluded
the tips, we would have strings doubled, once in help and once in tips -
and it makes no sense to manage and translate them separately.

but they are between tags <ahelp>the extended tooltip</ahelp>, so
extracted them will remove them from the help, and will not duplicate them.

Together with technical solution, I think we should also have a general
discussion about help and how it should look like: for instance, do we want
pictures and screenshots in it? Or any example files, external links...
etc. etc.

Yes, and I know that we have different opinions here (mine for example
is to keep it light and simple :slight_smile: However, I think we should first work
on the existing help files, move the process of amending the help on the
wiki forward and see how the translation workflow goes. When we will be
there, we should have a discussion about the content itself and its
evolution.

Kind regards
Sophie

#9

Hi,

> I would add one more point: currently, a lot of extended tooltips (maybe
> most of them) are directly part of the help text. Therefore, if we
excluded
> the tips, we would have strings doubled, once in help and once in tips -
> and it makes no sense to manage and translate them separately.

but they are between tags <ahelp>the extended tooltip</ahelp>, so
extracted them will remove them from the help, and will not duplicate them.

That's true only for <ahelp> with attribute visibility="hidden" (unless we
want to remove help parts:).

Let's see an example:
Help page: https://help.libreoffice.org/Common/Spelling_and_Grammar
and its source:
http://opengrok.libreoffice.org/xref/help/source/text/shared/01/06010000.xhp

The sentence "Specifies the language to use to check the spelling." is
<ahelp> and appears as extended tooltip and also in the help page.
On the other side, the sentence "While performing a grammar check, click
Ignore Rule..." doesn't appear in the help page, because it is <ahelp
visibility="hidden">.

>
> Together with technical solution, I think we should also have a general
> discussion about help and how it should look like: for instance, do we
want
> pictures and screenshots in it? Or any example files, external links...
> etc. etc.

Yes, and I know that we have different opinions here (mine for example
is to keep it light and simple :slight_smile: However, I think we should first work
on the existing help files, move the process of amending the help on the
wiki forward and see how the translation workflow goes. When we will be
there, we should have a discussion about the content itself and its
evolution.

I agree that this discussion should be kept for later; I just wanted to
remind this, maybe possibility to add such features can play a role when
designing the new system.

Best regards,
Stanislav

#10

Hi Sophie, Stanislav,

Sophie píše v St 02. 07. 2014 v 16:27 +0200:

> I would add one more point: currently, a lot of extended tooltips (maybe
> most of them) are directly part of the help text. Therefore, if we excluded
> the tips, we would have strings doubled, once in help and once in tips -
> and it makes no sense to manage and translate them separately.

but they are between tags <ahelp>the extended tooltip</ahelp>, so
extracted them will remove them from the help, and will not duplicate them.

Stanislav actually has a very good point here; this is something that we
have take into account when doing this, and I forgot about this. I mean
- even when the extended tooltips are enclosed in the <ahelp> tags, they
are still visible in the help text too; so we cannot just remove them
from there.

So there are 3 possible solutions for this that I can see [but maybe
Markus sees even another ;-)]:

1) Actually keep the extended tooltips as part of the help, tag them
   there some way (using a wiki template, or a simple extension) and
   only extract that to separate files that would be shipped
   accordingly. That means, even the extended tooltips would be
   translated using the mediawiki Translate extension.

2) Separate them, but create a wiki extension that would be able to
   obtain the extended tooltips source + translation from the Pootle.

3) Import the translations once, and just let them diverge.

I guess 3) is definitely not the way to go :wink:

I believe 1) is the easiest from the development point of view, and I
think also most consistent for translation - as you won't have to sync
between 2 tools to get the help completely translated. But now I am not
completely sure how that fits the Markus' current tooling that he has
already prototyped - Markus, can we translate even the extended tooltips
in the Translate extension? Does that fit you?

All the best,
Kendy

#11

Hi Kendy

There is a 4th option. I just checked on master that each *.ui dialog
widget has a tooltip entry that can be filled/edited inside Glade. The
tooltip shows upon hovering the widget.

So the <ahelp></ahelp> content can be moved inside the *.ui and thus
land in the Pootle UI project.

I must admit that it will be a extenuous job to move the <ahelp> entries
to the ui dialogs, if done manually and without some sorting per
module/dialog.

Olivier

#12

Hey,

Hi Sophie, Stanislav,

Sophie píše v St 02. 07. 2014 v 16:27 +0200:

> > I would add one more point: currently, a lot of extended tooltips
(maybe
> > most of them) are directly part of the help text. Therefore, if we
excluded
> > the tips, we would have strings doubled, once in help and once in tips
-
> > and it makes no sense to manage and translate them separately.
>
> but they are between tags <ahelp>the extended tooltip</ahelp>, so
> extracted them will remove them from the help, and will not duplicate
them.

Stanislav actually has a very good point here; this is something that we
have take into account when doing this, and I forgot about this. I mean
- even when the extended tooltips are enclosed in the <ahelp> tags, they
are still visible in the help text too; so we cannot just remove them
from there.

So there are 3 possible solutions for this that I can see [but maybe
Markus sees even another ;-)]:

1) Actually keep the extended tooltips as part of the help, tag them
   there some way (using a wiki template, or a simple extension) and
   only extract that to separate files that would be shipped
   accordingly. That means, even the extended tooltips would be
   translated using the mediawiki Translate extension.

2) Separate them, but create a wiki extension that would be able to
   obtain the extended tooltips source + translation from the Pootle.

3) Import the translations once, and just let them diverge.

I guess 3) is definitely not the way to go :wink:

Sadly I think it might be the only one that is a long term solution. So in
general I think it would be good to split the extended tooltips from the
help.

I believe 1) is the easiest from the development point of view, and I
think also most consistent for translation - as you won't have to sync
between 2 tools to get the help completely translated. But now I am not
completely sure how that fits the Markus' current tooling that he has
already prototyped - Markus, can we translate even the extended tooltips
in the Translate extension? Does that fit you?

I have no idea if that is possible. The biggest problem would be the ones
that are not part of the visible help texts.

Currently I personally would tend to the third solution but I understand
the concerns of the translators. My idea was that as we keep the already
translated strings this is not too bad. The hope with this was also that
the extended tooltips will be much easier to handle. Currently you need to
write the help texts therefore the extended tooltips are missing for a lot
of features. I'm not sure what we should do here and how many of the
tooltips are actually hidden/visible in the help.

Independent of the solution for the tooltips we will need to provide them
as po files to the Libreoffice build and have a mapping Libreoffice IDs to
the tooltips. So we would need to keep the same information in at least two
places and always remember to update both if we change the source code.

Regards,
Markus

#13

Hi Markus,

Markus Mohrhard píše v St 02. 07. 2014 v 18:51 +0200:

        I believe 1) is the easiest from the development point of
        view, and I
        think also most consistent for translation - as you won't have
        to sync
        between 2 tools to get the help completely translated. But
        now I am not
        completely sure how that fits the Markus' current tooling that
        he has
        already prototyped - Markus, can we translate even the
        extended tooltips
        in the Translate extension? Does that fit you?

I have no idea if that is possible. The biggest problem would be the
ones that are not part of the visible help texts.

Ah yes; so I thought there would be a special page that would only hold
those invisible ones.

I mean, if we had them all using a template like

{{Tooltip|modules/swriter/ui/flddocinfopage/fixed|Inserts the field as static content, that is, the field cannot be updated.}}

it could be used inline for the visible ones, or in a special page that
wouldn't be part of the help itself for the invisible ones. But no idea
if the Translate extension can extract only the parameter of the
template in some way if we mark it so, or if the entire above template
definition would appear for translation.

Having said that - seeing what actually is being used as the extended
tooltips, I am not sure if it is a huge loss if we go the 3) way, as
Markus points out:

Currently I personally would tend to the third solution but I
understand the concerns of the translators. My idea was that as we
keep the already translated strings this is not too bad.

All the best,
Kendy