Re: [libreoffice-users] LibreOffice's documentation (pdf and online)

On 06/25/2015 12:56 AM, Dave Barton wrote:

> To the best of my knowledge, only one of those USERS has professional
> writing skills and without her tireless input from day one neither the

FWIW, several of the people on the Documentation Team, published books
and other material, prior to volunteering on the documentation project.

> Of course it's possible to create documentation in the form of videos,

What happened to the people that were creating documentation in video
format?

That said, I've periodically looked at creating video documentation, and
realized that it is much simpler, and easier, to create a PDF, than to
create the video.

Perhaps what is needed, is an individual, or team, that can pick up the
documentation in ODF format, convert it to a storyboard, and then create
the video.

> epub, 

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. (You still have to manually strip out all of the
<span> markup code in the resulting ePub.)

> slide presentations

What happened to the people that were creating documentation, in the
form of slide presentations?

> There is just one tiny trivial problem, finding the army willing
volunteers to take on these tasks.

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 is good, but the research priority should be how to find and
keep documentation contributors.

We don't need research on how to find and keep documentation
contributors. (I'm not saying that the running average of new volunteers
is great.)

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.

I'll take what should be a trivial task, that should not take more than
thirty seconds. Find and install xmlhelptemplate.ott.

The second, and what should also be a trivial task, is locating and
installing Helpauthoring.oxt.

Time how long it takes you to locate both of those files.  Then time how
long it takes you to install them, assuming you can install them in the
first place.

That exercise explains why the built-in help is so wildly inconsistent
in quality.

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.

The core manuals being:
* Getting Started;
* Base;
* Calc;
* Writer;
* Math;
* Impress;
* Draw;

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.

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

The third group is the one that creates and maintains the online
documentation. The most urgent task needed there, which looks like, and
has been described as "an easy hack", is extremely complicated.

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

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.

jonathon


-- 
To unsubscribe e-mail to: users+unsubscribe@global.libreoffice.org
Problems? http://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/
Posting guidelines + more: http://wiki.documentfoundation.org/Netiquette
List archive: http://listarchives.libreoffice.org/global/users/
All messages sent to this list will be publicly archived and cannot be deleted