Intro and some questions

Hi all,

Below (far below) is a compilation of answers to several questions I had
about LibreOffice's documentation and processes. I have a few remarks at
this time (more later):

A couple of people (those from the User group as well), talked about
video. I have to say that I think that thinking about Video is way beyond
our capacity in terms of resources. As has been said over and over by those
who responded, there is just too much to do and too few people to do it.
(But I, of course, understand that anyone can do whatever pleases them in
this environment.)

There's been lots said about translation and L10N. Seriously, I'm not sure
what points were being made. In my view, we as the documentation team ought
do everything we can to make translation as available and efficient as we
can, but that is the extent of our work concerning it.

I have one specific question that maybe someone can answer for me. Someone
said, “* Excluding people whose legal residence is in a jurisdiction that
prohibits them to do these tasks, unless they are being paid to do so.”
What does that mean? Someone somewhere in the world would be legally
prohibited from volunteering? In any case, I would think that, if that were
the case, that's not our concern or responsibility. It would be the
volunteers. We can't police that.

I have been working on the “UsingAssistiveTechnologyInLO” doc. And I am
finding that information on LibreOffice is widely scattered. So far, I've
found info on Assistive Tech in the following locations. (I know many (most
probably) of you know this. I just want to bring it up.)

https://wiki.documentfoundation.org/Accessibility

http://www.libreoffice.org/get-help/accessibility/

https://help.libreoffice.org/Common/Assistive_Tools_in

https://help.libreoffice.org/Common/Accessibility_in

https://help.libreoffice.org/Common/Shortcuts_Accessibility

https://help.libreoffice.org/Common/Accessibility

Not only is tech information scattered, but even information about writers
and writing is scattered. It makes it hard to keep track and focus. At
least for me.

We are really low on man(woman) power. And I think one reason for this is
because things are really scattered. I think that organization would
attract or at least keep resources. As I had said before, it seems that the
doc team does get volunteers, but these volunteers seem to have no
direction, and so fade away.

LibreOffice has, as you all know, three completely separate documentation
teams. Three groups writing about essentially the same thing. Has the idea
to consolidate this effort ever come up? I know that some think that online
help and printed help ought be different. I don't disagree, but I think
this is a separate issue from that of consolidation. Even with differences,
there is still a great deal of duplicated effort. This duplication and
wasted effort is the real question I have for the group.

I am certainly aware that a consolidation or merging would take a lot of
effort. However, once that were accomplished, even if we had no new talent
coming to us, what talent we did have would be far more efficiently
utilized.

Now I know I'm not saying anything that most of you don't already know. I
just want to bring up the discussion to see if we can't do something with
it.

I have more thoughts, but I'll leave it as this for now.

(Once again I'm going to say that I hope I haven't offended anyone with
anything I have said. That surely isn't my intent.)

Thanks for everyone's responses.

Davidaa

Documentation Production

Online help comes from the developers of the project.

Historically, the group that produces the PDFs, and the group that produces
the built in help file have been entirely separate groups. As best as I can
tell, information available to one, has not been passed
onto the other group.

This works both ways. There is information in the help file that is
current, and accurate, but not reflects in the PDFs. There is information
in the PDFs that is current and accurate, but not reflected in the Help
File.

We don't know who is currently responsible for the creation of the online
help.

We are trying to find a way to simplify the process. But it's not all about
the process, we also need people to participate to it, for the moment there
are very few interested, so anybody is welcome :slight_smile:

… There are very few people producing anything in the way of documentation.
This applies both to creating original content, and translating existing
content from one language into another language.

… There is a lot of work to be done, but no single document that either
lists everything that needs to be done, or even lists everything that is
currently being worked on.

The User Guide Tasks page is supposed to be updated by people when they
check out files (from the ODFAuthors website) for updating, review,
editing, etc, and when they return the files they've been working on.
Unfortunately, many people fail to do this. No one in particular maintains
the page.

At the moment, it's essentially empty because very few people are working
on anything, AFAIK.

We don't have anyone coordinating documentation or mentoring new people.

Three groups? 1) pdf 2) Online help 3) Built-in Help.

The PDF files are produced by the documentation team, Online help is what
you find on the wiki help but also off line, maintained by developers and
l10n team. The third group is the Native Language
projects where documentation, marqueting, websites, QA etc are translated
and documented.

Technically there are two issues:
* Finding people that are willing to do it;
* Excluding people whose legal residence is in a jurisdiction that
prohibits them to do these tasks, unless they are being paid to do so;

Research priority should be how to find and keep documentation
contributors. What is needed, is a reduction in the barriers that new
contributors face, in creating/maintaining documentation.

For starters, there are three different groups that are involved in
creating/maintaining documentation. Each group has its own templates, set
of procedures, priorities, and barriers to participation.

With the documentation produced at ODFAuthors, the primary issue is, quite
literally, getting them started in the (¿easy?) things, like proof-reading
and copy-editing.

Something that isn't clear to most new contributors, is that whilst the
focus is on the six core manuals, there are a score of other manuals that
are on the wish-list.

Most of the focus is on the core manuals:
* Getting Started;
* Writer;
* Calc;

Secondary manuals are:
* Draw;
* Impress;

Tertiary manuals are:
* Math;
* Base;

The wish list consists of:
* Intermediate usage of those components;
* Advanced usage of those components;
* _Migrating from MSO to LibO_;
* _Site Administration of LibO_;
* _Creation and Distribution of Templates and Extensions_;
* _Using R in Calc_;
* _Project Management Using LibO_;
* _Accessibility and LibreOffice_;
I've forgotten the other topics.

The first documentation available to all users, whatever the language, is
the off line help, which is then duplicate to the wiki help. This
documentation needs much more love and is more and more outdated. We are
aware of it and would like to set a group to work on it.

Multiracio dispensed with PDFs, with the expectation that users will hit
F1. Consequently, the helpfile in EuroOffice, for Linux, is more accurate,
and much more useful than that of either AOo or LibO.

The major reason the documentation is not also available in ePub format, is
because there have been precious few requests for it to be in that format.
Nonetheless Jean has modified the template used by ODFAuthors, so that
export to ePub format is more reliable, consistent, and professional
looking.

and, for community/contribution interested users:
+ collaborativly created (like a wiki) - (which is different from comment
function!)
+ nice2have: views/downloads counter

L10N

Related to the issue of Documentation, is the issue of Translation.

There are also a dozen or so other documents, that would be useful, if
translated into English, and other languages.

Most people don't realize that L10N teams are responsible for translation
of the UI, the Built-In Help, the documentation on the website, and
creating/translating user guides in the local language(s).

We aren't yet at the point where machine translation is as good a human
translation is.

“* Excluding people whose legal residence is in a jurisdiction that
prohibits them to do these tasks, unless they are being paid to do so.”
What does that mean?

Someone somewhere in the world would be legally prohibited from

volunteering?

In a nutshell, individuals can volunteer, but the organization has to
pay them. Being a registered charity (British Commonwealth), or
501(c)(3) (United States) does not live the organization of the
requirement to pay those who would do the tasks voluntarily, and without
pay. Most of this legislation was passed during, and shortly after the
dot-bomb experience. Consequently, Tech orientated companies tend to get
special scrutiny by the Labour Board.

the case, that's not our concern or responsibility. It would be the volunteers. We can't police that.

Thing is, in most jurisdictions with such legislation, anybody can file
the complaint. The onus is on the organization, not the volunteer.

found info on Assistive Tech in the following locations. (I know many (most

https://wiki.documentfoundation.org/Accessibility
http://www.libreoffice.org/get-help/accessibility/
https://help.libreoffice.org/Common/Assistive_Tools_in
https://help.libreoffice.org/Common/Accessibility_in
https://help.libreoffice.org/Common/Shortcuts_Accessibility
https://help.libreoffice.org/Common/Accessibility

Also the mailing lists. Both the one specifically for a11y issues, and
the l10n projects. Maybe also the user list.

I don't remember which project had A11Y How-Tos in bugzilla.

Not only is tech information scattered, but even information about writers
and writing is scattered. It makes it hard to keep track and focus. At least for me.

I suspect that the same is true for all of the projects within LibO.
The information is out there, but because it scattered in umpteen
different places, few people manage to track it.

jonathon