Re: Ease maintenance of build-in help

Hi Regina and all the rest. 

First of all, I'm not (yet at least) a developer. That said I'll toss in my thoughts because I AM 
very concerned about the quality and accuracy of LibreOffice's built-in help.

[May I suggest that all responses to this thread should utilize the Reply All mechanism but stay on 
topic. Private (off list) replies are not very helpful in a discussion like this.]

Regarding concensus that the current built-in help will be retained: In my opinion something like 
it MUST exist. As frustrating as the current verbiage is, to toss it out entirely would be far 
worse. Rather, let's incrementally improve it.

A
This seems to be common sense. (+1)

B
I know nothing about this extension but if it makes it easier for "Joe Sixpack" (a run of the mill 
user of LibreOffice) to productively contribute to the quality of the built-in help then I'm all 
for it. (+1)

C
Most emphatically,  yes. (+3) To improve its visibility to the user community someone should add a 
link to this wiki in the top level Help menu (something like "How to contribute to this Help")

D
Way to go! Those who contribute any documentation, particularly in the early stages, need not be 
programmers who are battle scarred from waging the battle to build the software. (+2)

-- 
Jim

-----Original Message-----
From: Regina Henschel <rb.henschel@t-online.de>
To: LO dev fdo <libreoffice@lists.freedesktop.org>
Cc: LO documentation <documentation@global.libreoffice.org>
Sent: Sun, 02 Aug 2015 10:07
Subject: Ease maintenance of build-in help

Hi all,

I have started a new thread so that the problem is not hidden inside 
other threads or in private mails.

First, is there consensus, that the current build-in help will be retained?

If not, then the following ideas are useless and starting would be waste 
of time. In such case, please stop me immediately.

I collect here some ideas from some threads and mails:

A
Authors of help texts are allowed to start in ODF to discuss and 
finalize the content and appearance of the intended help texts. There 
should be a place in the repository to store such files. This way 
authors did not need deep knowledge of the technical structure of 
helpcontent2. The person who integrates the help texts into the build-in 
help need not be the content author.

B
Improve the extension "HelpAuthoring" and fix its bugs. The extension 
might be principally not suitable to generate the final version of a 
help file, but it is useful as start, because it sets a lot of the 
needed XML-elements and attributes automatically. The result might still 
needs additions and corrections, but that is less work, than writing all 
from scratch. Even if someone do not know all details about the help, he 
can start and deliver a file, which other then can improve and integrate.

C
Provide a development section about the build-in help to the Wiki. It 
should not only contain a tutorial about help authoring but in addition 
a description how the current help works at all from a developer view, 
and how it is actually structured.
We can start with the document "OOo2HelpAuthoring.pdf". The content has 
to be revised and adapted and extended. For example the .mk files are 
different than described in that document and the document describes the 
possibilities of the help format, but not all details of the actual 
realization.
Having it in the Wiki keeps such knowledge available, when a help expert 
leaves the community. It can be adapted to future developments. Experts 
of different areas can better work together to collect help knowledge in 
one place, for example experts for "Help to Wiki" and experts for 
"translating help".

D
It would ease work, when there would be a tool, that shows a .xhp file 
the same way as it it shown in the help viewer, so that it is not needed 
to build helpcontent2 every time when you test some changes in your way 
to the final version. And authors who use "HelpAuthoring" need not be 
able to build LibreOffice.

Kind regards
Regina

_______________________________________________
LibreOffice mailing list
LibreOffice@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/libreoffice