Intro and some questions

Hi all,

I have a lot of time on my hands and so wish to contribute to LibreOffice's
documentation.
I have a background in publishing, computer support, database application
programming, and, most recently, as Senior Technical Writer for Trend Micro
for seven years. I was responsible for some of Trend's major product
document sets.
I've seen the page titled "User Guide Tasks" (
http://wiki.documentfoundation.org/Documentation/Development), but it's
essentially empty. Is it maintained by anyone in particular? If not, how is
it updated?
Is it fair to say that I could "just pick something" to work on because,
essentially, little to nothing is being worked on?
I see a few people recently showing interest in LibreOffice's
documentation, but I don't know if they are working on something but not
updating the list or they aren't doing anything simply because they're
getting lost in such a huge project--especially if those volunteering are
new to documentation.
I'm just finding it difficult to jump into details without knowing the
overall picture.
Anyway, just thoughts. Maybe there's something I'm not seeing clearly? I
don't wish to offend anyone.
I need to get an ODFAuthors account. Can someone help me with that?

Thanks,
David Allen

I've seen the page titled "User Guide Tasks" (
http://wiki.documentfoundation.org/Documentation/Development), but it's
essentially empty. Is it maintained by anyone in particular?

That page is more a description of how things are done, than what is done.
http://www.odfauthors.org/libreoffice/english/resources-for-contributers
is a better description of the system used by ODFAuthors.

Wandering through the projects listed in the column on the left hand
side, will provide a more current status of the documentation process.

http://www.odfauthors.org/libreoffice/english/ is where to start, to
find a reasonable current list of what is being done, in English.

Is it fair to say that I could "just pick something" to work on because,
essentially, little to nothing is being worked on?

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

Secondary manuals are:
* Draw;
* Impress;

Tertiary manuals are:
* Math;
* Base;

If you know contemporary geek German, and want to help get the material
ready for LibO 5.0, my suggestion would be translate the German manual
on Base into English, then update it to LibO 5.0.

I just discovered that _Using Assistive Technology in LibreOffice_
hasn't been updated since 2010, and at that, it is extremely incomplete.
«IMNSHO, this document should be platform specific, describing how the
various a11y do, or more commonly don't work with LibO, and what the
viable workarounds are.»

or they aren't doing anything simply because they're getting lost in such a huge project

Part of it is that 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.

Part of it is that 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.

«Creating that groups of documents would be a good test of the
functionality of the Project Management tools for Lib0.»

especially if those volunteering are new to documentation.

That is a good point.

Some people have selected their own specialty within documentation, and
are working on it at a glacial speed.

jonathon

I've seen the page titled "User Guide Tasks" (
http://wiki.documentfoundation.org/Documentation/Development), but it's
essentially empty. Is it maintained by anyone in particular? If not, how is
it updated?

The User Guide Tasks page
(https://wiki.documentfoundation.org/Documentation/Development/UserGuideTasks)
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. I, and a few others, occasionally fill in
spaces for other people, but no one in particular maintains the page.

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

Is it fair to say that I could "just pick something" to work on because,
essentially, little to nothing is being worked on?

In most cases, yes.

I see a few people recently showing interest in LibreOffice's
documentation, but I don't know if they are working on something but not
updating the list or they aren't doing anything simply because they're
getting lost in such a huge project--especially if those volunteering are
new to documentation.
I'm just finding it difficult to jump into details without knowing the
overall picture.

We don't have anyone coordinating documentation or mentoring new
people. I was doing that for years, but I've retired from that work.
The Contributors Guide is useful but somewhat out of date and
incomplete. I believe Dave Barton is updating some chapters.

Anyway, just thoughts. Maybe there's something I'm not seeing clearly? I
don't wish to offend anyone.
I need to get an ODFAuthors account. Can someone help me with that?

I'll set that up for you now. You should soon get an email with your login info.

--Jean

Hi Jonathon and Jean,
   Thanks for your replies.
   Sorry, I don't know German. Or any other language (Just a few words in
Chinese; I lived in Taiwan for seven years).
   I found the _Using Assistive Technology in LibreOffice_ document. It's
labeled "draft 2". Do either of you know if this is this the latest
version? Also, was this document meant to be part of another doc, like an
appendix to the GSG, or was it to remain a separate doc?
   Jonathon, you mentioned "a good test of the functionality of the Project
Management tools for Lib0". Are you talking about a specific piece of
software?
   Jean, thanks for the account.
Davidaa

Management tools for Lib0". Are you talking about a specific piece of
software?

Over the years, individuals and organizations have submitted extensions
and/or templates that ostensibly enable one to manage projects, using
OOo, and then LibO or AOO.

After I wrote that email yesterday, I went browsing the LibO and AOo
extension sites, and only two extensions popped up under a search for
"project management". DatabaseRangeManager, and AuthorSupportTools.
* DatabaseRangeManager, when correctly configured, ensures that sane
values are inserted into spreadsheets. (I didn't test this extension out.)
* AuthorSupportTools looks like a fork/updated version of Writer Tools,
and Writer Extras. In both LibO 4.3.2 & LibO 5.0 beta, it crashed on me,
with an unsupported Java call. It wouldn't install in EuroOffice 2014.

At Libreoffice Templates, there is a Gantt Chart Template, and a Project
Manager Database.
* I used The Gantt Chart Template for a project a while ago, and it
works fairly well, provided one has a list of required resources, and
all the other data it requires, before creating the chart. (This is a
major issue with Gantt Charts.)
* I just briefly looked at the Project Manager Database, and it looks
promising. However, I haven't tried it out, so looks may be not be accurate.

There are ten templates at Apache OpenOffice Templates that purport to
be for project management. The ones I looked were straight conversions
from Excel. At least one required whatever scripting language Excel
uses, to be available.

Something I didn't find, that I thought I'd seen, but on reflection
probably only saw the spec sheet/wishlist of, was an extension that kept
the data in BASE, used Calc for data input/output, exported
dates/schedule to IC and Lightning, and sent reminder/status report
emails via Thunderbird.

jonathon

  * English - detected
  * English

  * English

<javascript:void(0);> <#>

Hi Jonathon and Jean (and everyone else),
   I've been using LibreOffice for years as a PortableApp (from
PortableApps.com), and I never knew there was local online help. It
apparently doesn't install with the Portable version.
   Do either of you (or anyone else) know where this online help comes
from? Who is responsible for it? How it is created? It's totally different
from the pdfs.
Thanks,
Davidaa

and I never knew there was local online help. It apparently doesn't install with the Portable version.

If Ann-ology hadn't writing "what documentation?" in her comment, I
wouldn't have thought to toss that paragraph about the Online Help into
my response to her comment.

Do either of you (or anyone else) know where this online help comes from?

The developers of the project.

That isn't as bad, or as bizarre as it sounds.
When Sun purchased StarOffice, there were one or two people, whose job
was to convert the specs used by the developers, into the content that
is in the help file.

Today, the remnants of those spec sheets can be found scattered
throughout different parts of both the LibO and AOo websites.

There is also a lot of what can be termed "institutional knowledge".
Things that are known to people who have worked on the project for
years, and, in most cases, has documented somewhere in the project, but
nobody else is even aware of that body of knowledge, regardless of
public accessibility of the documents with that knowledge.

The online help is maintained by the developers.
https://wiki.documentfoundation.org/HelpContent

Sophie can point you to more information.

--Jean

My responses are given in-line with your original message.

How it is created

Painfully :slight_smile:

Going by the comments in email list about creating the helpfile, I
suspect that "painfully" is a major understatement.

The dev guide to creating help files can be found here:
https://wiki.documentfoundation.org/HelpContent
and a somewhat dated edition here:
http://www.openoffice.org/documentation/online_help/

One needs to find:
* Helpauthoring.oxt.
* xmlhelptemplate.ott

and learn how to use both of those items, before one can even begin to
work on the built-in help documentation.

As best as I can determine, there is no documentation on how to use
either the template, or the extension.

The other barrier is setting up GIT/Mercurial/whatever SVN is really
used, on one's local system, to import the data onto one's system.

sudo apt-get install GIT is easy enough, but to use it is a slightly
different story.

BTW. We are all subscribed to this list, so cc isn't necessary.

My working assumption is that the person sending the reply has little,
if any control over who receives their reply, when responding to a list.

jonathon

Hi all,

How it is created

Painfully :slight_smile:

Going by the comments in email list about creating the helpfile, I
suspect that "painfully" is a major understatement.

We are reviving the old extension to handle helpfiles through
LibreOffice, it's much easier than editing the xml files.

The dev guide to creating help files can be found here:
https://wiki.documentfoundation.org/HelpContent
and a somewhat dated edition here:
http://www.openoffice.org/documentation/online_help/

One needs to find:
* Helpauthoring.oxt.
* xmlhelptemplate.ott

We were discussing where to place the files, they will be made available
once the ESC has decided where it should go, as well as the two .xml
files I discuss on the wiki page and currently on my computer.

and learn how to use both of those items, before one can even begin to
work on the built-in help documentation.

As best as I can determine, there is no documentation on how to use
either the template, or the extension.

There is, I need to update it. I've created the wiki page last week and
still have to enhance it.

The other barrier is setting up GIT/Mercurial/whatever SVN is really
used, on one's local system, to import the data onto one's system.

sudo apt-get install GIT is easy enough, but to use it is a slightly
different story.

You don't need that, putting the file on an issue is enough.
As said at the beginning 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:

Cheers
Sophie

Hi Jonathon,

The HelpFile documentation was originally created more or less according
to what those spec sheets say, with, what appears to me, to be minimal
testing of whether or not the implementation is congruent with those
specification sheets.

Sums it up pretty well IMO. Being one of those ancient volunteers from
the days when OOo was first released, the integrated Help was actually
more complete than it is now. At some point in time (I don't remember
when exactly, but possibly between OOo 2 and OOo3 development, a
decision was made to slim down the help content, when the switch was
made to XML files instead of what I believe was a binary encoded help
system (at that time). Needless to say, this didn't improve the overall
quality and relevance of the integrated help. There are attempts at
improving it though.

I believe that there is/was an extension that facilitates writing help
content, although I haven't looked recently at how that integrates with
the project's git code repo and submission by any volunteer - probably
slightly more complicated than most people are prepared to accept. The
wiki help is supposed to allow an easier transition into allowing
volunteers to write help documentation, but again, knowing where to put
stuff, and learning to use mediawiki is an extra hurdle for a lot of
people who would be perfectly happy just writing stuff without having to
worry about code.

If Sophie or someone else from the l10n project is reading this thread,
they might be able to say more about where the project is today with
facilitating creation (and maintenance) of help content.

Alex

I had forgotten that it used MediaWiki.

Creating content is as easy as:
# Create the new content in LibreOffice;
# Export the document to the wiki using the built-in Wiki Publisher
extension;

I thought that there was an extension that enabled one to grab content
directly from the web, but I can't find it.
Maybe I'm thinking of the "Copy Plain text" extension for FireFox.

jonathon

  * English - detected
  * English

  * English

<javascript:void(0);> <#>

The LO Help found on the wiki is generated from the XML files Sophie
mentioned elsewhere in this discussion. DO NOT edit the Help on the
wiki, because your edits will NOT get back into the Help distributed
with the program, and any edits on the wiki will be over-written the
next time the wiki-based Help is generated from the XML files.

(If my information here is out of date, Sophie will correct me.)

--Jean

Further thoughts: I don't have time to check on this, but it's possible the
LO Help pages on the wiki are locked against editing except by specific
people. If so, you won't be able to edit them anyway.

--Jean