LibreOffice WikiHelp

Hi,

Please, let us decide of how we are working. Again, we are not newcomers
here. We take care to provide a product of very good quality since years. If
you don't want to speak with us, please, do not try to provide tools and
systems we don't need and want at all.

I am slightly confused by this statement. Clearly there is a dialogue
going on in each functional team to achieve the best outcome possible.
This discussion is case in point.
Sophie, It seems you are feeling left out of the decision making
process. How are we able to resolve this?

Does Kendy come to discuss the wiki idea with the l10n groups? No. Does he answer the question we asked? No. So as part of the team taking care or the help files and it's quality, yes we are left out, it's even not a question.

Idea: The i10n team currently does not have wiki page. Could I suggest
that if the i10n team create their own page so the requirements for
native language teams can be coordinated and other projects can meet
those requirements.

You will end by having people using other tools to fit their needs, that's
all, I'm not sure this is what you want. Clearly, if you don't want to
understand how it works, how we work, you're going to loose your time
because the language groups will use their own CMS and tools and will go
away from the main site.

Sophie, it might be good for you to contribute here in a positive way
to ensure your needs are met by this fantastic new tool that Kendy has
built.
Kendy, you might be able to comment on this. But as I understand it
there is not going to be the option for language groups to break off
and create their own help wiki?

The tool we work with is Pootle and we don't want a wiki or anything else. Pootle allow us to work offline which is very very important.
Pootle allow us to use our translation memory, we are able to let comment for each segment and make proposal. We have syntax rules and several checks tools available (punctuation, marks, tags, etc). We are able to ensure the quality of the file we are delivering with it. Why should we change our way of work when we are efficient and happy with it, without even asking us what we think about it. The help files are as important as the product in itself, so why should anybody be able to edit it without any idea of the process that ensure the coherence and the cohesion of it?

Kind regards
Sophie

Nobody has stated anything like "We will not be using Pootle" in fact
I know that Drupal supports the use of .po files and I am pretty sure
that Mediawiki does also.
As I mentioned before, it might be worth mentioning this first to see
if your concerns have been considered rather than jumping to
conclusions in an accusing way.

Kendy, you might be able to field these concerns further.

The tool we work with is Pootle and we don't want a wiki or anything else.
Pootle allow us to work offline which is very very important.
Pootle allow us to use our translation memory, we are able to let comment
for each segment and make proposal. We have syntax rules and several checks
tools available (punctuation, marks, tags, etc). We are able to ensure the
quality of the file we are delivering with it. Why should we change our way
of work when we are efficient and happy with it, without even asking us what
we think about it. The help files are as important as the product in itself,
so why should anybody be able to edit it without any idea of the process
that ensure the coherence and the cohesion of it?

Nobody has stated anything like "We will not be using Pootle" in fact
I know that Drupal supports the use of .po files and I am pretty sure
that Mediawiki does also.

It's not the use of .po files that is important here, it's about the tools provided by Pootle to manipulate .po and .xliff files online and offline

As I mentioned before, it might be worth mentioning this first to see
if your concerns have been considered rather than jumping to
conclusions in an accusing way.

"For now, editing features are disabled, so that we can fine tune the conversion tool. We plan to open it for your improvements with the LibreOffice 3.3 RC2. " RC2 is next week.

Kind regards
Sophie

Hi Miklos,

I must miss something really trivial, but I do not see where to start
reading. :slight_smile: The only way to find pages from the main page is to use the
Random page or Recent changes feature.

Did I miss the point? :slight_smile:

No you didn't. In fact you are spot on. If I were to put myself in the
position of a first time user of LibO and was directed to that page, I
would literally say "you gotta be joking !". What use is an online help
system in a wiki that doesn't show index links to the main topics. This
is a minimum for any help system. As for the search engine, well, I've
never been very impressed with most of the search engines used in
default wiki implementations.

The user must be given the possibility to browse through the pages of
help via links that appear, as they did in the "inline" help system of
OOo, otherwise as far as I'm concerned it is absolutely useless. If and
when the user comes across a topic for which they know the keyword to
search for, then they could of course use the search engine to enhance
their browsing experience, but IMHO you can not forego the immediate
visual need of a user. An example to look to in this case would be the
API documentation of OOo, yes, you can search for the terms using the
search engine that Collabnet provided, but you can also drill down via
links through the various API descriptions.

Whilst I appreciate that it must have taken a lot of work to get this up
onto the wiki, IMHO the visual accessibility of the information really
needs to be addressed.

Alex

Hi Kohei,

> > http://help.libreoffice.org is now up and running.
>
> Can someone post the IP address of that site? For me, that leads to the
> old go-ooo source code documentation by doxygen. It could be a DNS
> caching issue if we are trying to change the sub-domain routing.

Ah, nevermind. The real main page is

http://help.libreoffice.org/Main_Page.

How comes it is not redirected? Here it works just fine, ie. when I
type help.libreoffice.org in the browser, I get the Main_Page. I am
confused :slight_smile: - ideas appreciated.

Regards,
Kendy

Hi Miklos,

> http://help.libreoffice.org is now up and running. As explained above,
> it is not open for public editing yet.

I must miss something really trivial, but I do not see where to start
reading. :slight_smile: The only way to find pages from the main page is to use the
Random page or Recent changes feature.

Did I miss the point? :slight_smile:

You did :wink: The point is not to browse the help per se (even though it
can of course evolve into that), but the real usage is to hit F1 in
LibreOffice without a help installed, and you'll get _directly_ to the
right page - eg. if you navigate by keys in the File menu to 'Save
As...', and hit F1' you'll get directly to

http://help.libreoffice.org/Swriter/.uno:SaveAs

:slight_smile:

Similarly for the checkboxes/input fields/anything in the dialogs, or
wherever you can hit F1 and get some help.

Regards,
Kendy

Browser cache is the answer. Ctrl-R to the rescue.

Kohei

Hi Muthu,

I guess we should tie the 'help-welcome' (the page that opens when the
user clicks Help->Help from menu) pages to the wiki/Main_Page or
probably create a LibreOffice welcome help page (to point to the Writer,
Calc, and other applications help-start pages)...
I too felt it odd for it not to have it. Just my thought...

We have these, eg. when you hit F1 in a freshly opened Writer, you get
to:

http://help.libreoffice.org/Swriter/start

Actually - if anyone volunteers to improve the Main_Page (eg. collect
links to swriter/start, scalc/start, ...), I'll be happy to create the
account for him to do that; or I can cut and paste any improvements sent
to this thread directly as an wiki update.

Though - as I already explained, first it is necessary to fine-tune the
conversion tooling, the things like the exact wording of the Main_Page
can be fixed as soon as I feel confident with the result of the
conversion so that I can open it for everyone to edit.

Regards,
Kendy

> Did I miss the point? :slight_smile:

You did :wink: The point is not to browse the help per se (even though it
can of course evolve into that), but the real usage is to hit F1 in
LibreOffice without a help installed, and you'll get _directly_ to the
right page - eg. if you navigate by keys in the File menu to 'Save
As...', and hit F1' you'll get directly to

http://help.libreoffice.org/Swriter/.uno:SaveAs

Oh, I see. Thanks for the explanation.

Actually - if anyone volunteers to improve the Main_Page (eg. collect
links to swriter/start, scalc/start, ...), I'll be happy to create the
account for him to do that; or I can cut and paste any improvements sent
to this thread directly as an wiki update.

I guess it's not so hard to collect all the start pages if you have
access to the SQL db under the wiki - but without having that I would
put something like:

"For ease of access, the LibreOffice help has been split up into several
sections.

Yes, this main page needs a lot of work. Once we get around to doing
a good conversion, it will improve. We promise.

* [[Swriter/start|Writer]]
* [[Scalc/start|Calc]]
* [[Sdraw/start|Draw]]
* [[Simpress/start|Impress]]
* [[Smath/start|Math]]"

Hi Miklos,

> Actually - if anyone volunteers to improve the Main_Page (eg. collect
> links to swriter/start, scalc/start, ...), I'll be happy to create the
> account for him to do that; or I can cut and paste any improvements sent
> to this thread directly as an wiki update.

I guess it's not so hard to collect all the start pages if you have
access to the SQL db under the wiki - but without having that I would
put something like:

Cool, thank you a lot! Now it's there :slight_smile:

Regards,
Kendy

Hi all,

> Either way, the good news is that I am currently uploading the files,
> and I'll make the site online as soon as it finishes, and I do few
> trivial checks; it should be later today (ETA 5 more hours, I am
> populating the database through the Mediawiki API, not directly). So
> far I am uploading only the English version.
>
> It will be read-only until RC2, so that it is easy to report bugs
> against the tooling that converts the help from the format that is used
> in the source code. After RC2, I plan to open it for your edits &
> improvements :slight_smile:

http://help.libreoffice.org is now up and running. As explained above,
it is not open for public editing yet. There are few known bugs already
filed in the bugzilla, should you find more, please report them too,
with 'wikihelp: ' in the subject, and assign them directly to me.

The already reported bugs are:

https://bugs.freedesktop.org/show_bug.cgi?id=32173
https://bugs.freedesktop.org/show_bug.cgi?id=32174

You can either test the wikihelp directly from LibreOffice RC1, by
issuing help on various parts of the suite (if you find something that
leads to non-existing page, please report it too), or just from your
browser, using 'Random page' in the left hand menu, and visually
scanning it :slight_smile:

I'll improve the tooling according to your findings, and upload the
improved versions of the pages.

I got just 2 additional bugreports, I am not sure it is enough :wink:

https://bugs.freedesktop.org/show_bug.cgi?id=32290
https://bugs.freedesktop.org/show_bug.cgi?id=32291

All four are fixed now, but please - really test it. Until we are sure
that the quality of the conversion tool is good enough, it makes no
sense to upload the l10n versions of the help - it would unnecessarily
blow the size of the database with every improvement of the conversion
tool.

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 :slight_smile:

Thank you,
Kendy

Hi Kendy, :slight_smile:

I got just 2 additional bugreports, I am not sure it is enough :wink:

https://bugs.freedesktop.org/show_bug.cgi?id=32290
https://bugs.freedesktop.org/show_bug.cgi?id=32291

All four are fixed now, but please - really test it.  Until we are sure
that the quality of the conversion tool is good enough, it makes no
sense to upload the l10n versions of the help - it would unnecessarily
blow the size of the database with every improvement of the conversion
tool.

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 :slight_smile:

Personally, I'm taken up this weekend with other work for LibO but,
next week when I have more time, I will definitely look at the
WikiHelp and do my best to provide practical help.

David Nelson

Firefox warns that the connection is untrusted. (I think the warning comes from Google, which analyzes the threat from each site).

I did not visit the site because of that. Many more people may be avoiding the site in a similar manner.
Please ask the web master to take care of the issue (or contact Google to remove the false positive).

Then you will get many more volunteers.

Thanks.

-Narayan

Known problem related to the free cert used. For some reason browsers do not accept the cert which leads to the report.

Hi Kendy,

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 :slight_smile:

Any chance of getting entries for the Base Module, and Basic / Macros ?

Thanks,

Alex

Hi Kendy,

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 :slight_smile:

Any chance of getting entries for the Base Module, and Basic / Macros ?

Thanks,

Alex

Hi Kendy,

Hi all,

[...]

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 :slight_smile:

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.

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? will you stay there and spend your nights correcting the bugs newcomers have done or those not taking care of your previous work? No, you'll go away from such a project that do not care about your contributions and the quality of its product.

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.
Thanks in advance
Kind regards
Sophie

Hi Sophie,

> 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 :slight_smile:

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.

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.

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.

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 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.

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.

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?

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.

Thank you,
Kendy

Hi Michael, :slight_smile:

So - there is no need to open the wiki for editing ever, if that is a
huge problem for people, and certainly we don't have to do this for 3.3,
and certainly we don't have to open the wiki so just anyone can turn up
from the street and spam it :slight_smile: [ it is easy to have approved
translators only eg. ]. We can provide solutions for off-line editing,
and there is certainly no need to switch tooling to make the wiki the
authoritative data source now / yesterday :slight_smile: we can do that in a
month / never if there is some insuperable problem.

Personally, I like the idea of editing the help on the wiki rather than offline.
But could the problem be solved by creating a user group on the wiki and
only allowing editing rights for that group's users? Then we could add selected
devs, i10n and docs people to that group?

Is that a feasible solution?

David Nelson

Hi Kendy,

First, thanks for your answer:

Hi Sophie,

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 :slight_smile:

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 :slight_smile:

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