[Libreoffice] LibreOffice WikiHelp

[Sophie Gautier]

Hi Kendy,

First, thanks for your answer:
On 13/12/2010 13:20, Jan Holesovsky wrote:
> Hi Sophie,
>
> On 2010-12-11 at 14:35 +0300, Sophie Gautier wrote:
>
>>> I have heard quite some complaints about the missing native language
>>> versions already; I am not sure I've explained it well enough
>>> previously, but this testing is blocking it.  So please - help me :-)
>>
>> I've search for your explanation on our list but didn't find them.
>> Currently we (the localizer team) do not want the localized help to be
>> uploaded on the wiki until we know about the localization process that
>> will be in place.
>
> I have subscribed to the l10n mailing list just on Friday, after I
> learned that there were some discussions there I was not aware of until
> then.

This is the list for the people doing the work you're currently 
removing, so you should have come first to this list :-)
>
> Now, the explanation about wikihelp.  As you may recall, the conclusion
> was described as:
>
> 	create help-packs - split out the help for each language
> 	and simply have no help installed[1], but a web link to on-line
> 	help[2], and a "download your help-pack here" direction
> 		+ not even English help would be installed -
> 		  this will save us 11Mb in the 170Mb download
>
> Also, each and every release notes of betas and even RC1 contained a
> note "The help content is not included. We are working on the online
> version. Alternatively, it will be possible to install it separately."
>
> It is my mistake that I did not explain the exact way to implement it in
> advance, I am sorry for that.

It's ok, thanks for your explanations.
>
> So let me explain why wikihelp:
>
> Wiki is so far the best free tool for collaboration editing I know of.
> It gives anyone the freedom to improve things.  With help implemented as
> a wiki, any user of the suite can (potentially) just describe the
> functionality better, should he/she find out that something is described
> wrongly, or just partially.

We're used to work on the wiki, so yes, for documentation it's a very 
good tool.
>
> Also, why should be your native language just a translation of an
> English help?  Should you have people that can improve the help, but
> cannot speak English, why should they be bound to translating only, when
> they can author the text?  Why should be the French help just a
> translation of an English help, when it can be an own (better?) version?

This is all the difference between documentation and the help. Creating 
content is much more difficult than translating it and doesn't have the 
same cost. So offering the help files for translation ensure that all 
languages have access to the same basis of *accurate* information. This 
is what Help is and why it should stay in a localization process. 
Offering the same information at the lowest cost as possible.
If it needs to be completed, lets do it as we have done until now : 
using links pointing to the wiki (see the Calc functions, as an example).

As I said in my mail about HC2 and localization, we use some tooling to 
ensure the overall quality of the files. We won't be able to use them in 
a wiki, it's making our work very difficult to render the same quality 
as the one we are currently offering. We have style guides, and several 
checks available on Pootle.
Just an example : we often have to correct one string in the UI, to make 
sure it's changed in all the files where this string is appearing, we 
just grep and change the string. You won't be able to do that on a wiki. 
Also we make large use of suggestions and comments on strings, we work 
off line, we use translation memory and glossaries, etc. All these 
tooling ensure a quality of our work that you won't be able to use on a 
wiki.

>
> This is why I believe implementing the help as a wiki is the best thing
> to do.  How does it work:
>
> - for 3.3, I am converting the .xhp files into wiki markup
>    - it is now online as http://help.libreoffice.org
>    - missing translations yet, I need to polish the tooling first
>    - when the tooling is right, I'll add 2-3 more languages, for more
>      testing
>    - when even that approved, I'll upload the rest
>
> - anything untranslated in the localized versions will be marked
>    appropriately
>    - a template for that, like {{NeedsTranslation}} + the English version
>
> - after the import is done, and people are happy with it, it will be
>    open for account creation
>    - for now, please ask me directly if you want to have an account
>      there, to edit pages like Main_Page, or Template:*
>    - other pages might get rewritten by the import tooling
>
> - after 3.3, I'll start to work on tooling to convert it back to offline
>    help
>    - to platform native help system
>      - Windows/Linux/MacOSX
>    - from the engineering point of view, we don't want a home-grown help
>      system, as we have now
>    - needs more research, to see if we don't lose features etc.
>
> - when done, the wikihelp becomes the authoritative version of the help
>    - but we'll still be able to incorporate changes from the .xhp files,
>      when merging from OOo
>    - we can agree that some of the localized versions would be locked for
>      editing, and just taken from .xhp and .sdf files, but I _strongly_
>      advise against that
>
> Open questions:
>
> - extended tips
>    - cannot be part of the wikihelp, most probably these have to be
>      handled separately, and translated using the normal process
>
> - anything else?
>
>> We are the one doing the work and it's a very big work, so please,
>> answer the questions we have asked.
>> What if we open the git repository to anybody tomorrow?
>
> As you might have noticed, anybody can ask for the git account, and
> anybody with a bigger contribution is offered with write access.

"with bigger contribution" it is different from a wiki where anybody is 
able to create an account and start to work.
>
>>   will you stay
>> there and spend your nights correcting the bugs newcomers have done or
>> those not taking care of your previous work?
>
> Oh?  Were you following what we are doing on the development mailing
> list?  The last months, we have spent days and nights reviewing and
> fixing patches from new people.

yes, provided you can discuss with this people, on a wiki, you just 
create a account and can stay anonymous, unfortunately. Really, all the 
l10n teams have spent nights on these files, we wouldn't like see them 
destroy by a bot.
>
>>   No, you'll go away from
>> such a project that do not care about your contributions and the quality
>> of its product.
>
> Why do you think that people want to break your work?  Do you really
> think that making something yourself is more effective than just
> reviewing someone else's work?  How could it scale, if you were doing
> everything yourself?

No you misunderstand what I say, reviewing is the same for me, but a 
wiki is just open to every body without knowledge of stylistic, 
linguistic, and so on. That can damage a lot the quality of the content. 
This is not a documentation, it's really different.
>
>> So please, please again, answer the questions Martin asked, the
>> questions I asked, see Rimas and Jean-Baptiste mails too. And do not
>> open the wiki until we all agreed on the workflow, it's really important
>> for our localization team.
>
> Yes, will do, and sorry again that I haven't summarized all this before.
> If you can point me to the messages I probably missed due to not being
> subscribed to the l10n@ ML, that would be most appreciated.

Most of the time I've posted also on the dev list, so you may not have 
miss mine. But surely, Martin and Rimas one. I'll try to find them when 
I can reach the archives of the list.

Kind regards
Sophie