Page History

...

Current Situation and Issues

Structure

At present, the application help files are located in the source code module helpcontent2 with the following structure:

...

The biggest module is "shared" that takes all content that is valid for more than one application (which is most of the content) in order to make it available to the help viewer in all applications. But this leads to awkward side effects when content is valid for more than one but not all applications, yet it is still available for all applications. This leads to situations where the users finds content that is actually not in scope for his/her current context (but still visible since in shared) which can be pretty confusing.

Implementation with the application

The help viewer is a Writer/Web component wrapped in a nice UI and served by the help content provider. The appearance of the help UI is completely outdated, and so are its concepts (to separate between TOC, Index, Search, for example), and the fact that it's just a Writer document window in disguise can lead to all sorts of funny nasty side-effects. Also, the Writer/Web component has a hard time even displaying HTML 3.2 correctly, so the help files breathe the spirit of 1985. The full text search does not work correctly and never has.

UI Issues

The content and structure of the help files do not show a clear distinction between referential, conceptual and instructional information. On looking for guidance, users can stumble over files that just list the UI elements of a dialog with one explanatory sentence but with no indication of the context.

Maintenance Issues

• A rather complicated architecture (understatement!) in terms of maintenance. The only found document describing what's going on in any detail can be found at: Understanding and Authoring OpenOffice2.0Online Help. This is a cumbersome document which doesn't directly explain how to assign new ids to help items, where to put them etc., given the hierarchical nature of the help system.

• New volunteers desiring to get involved with authoring or changing any help item would likely need to install the "Help Authoring" extension, which can be found at: http://people.apache.org/~jsc/test/helpauthoring.oxt. Once this extension is installed, adding or changing help texts is a bit easier but followup maintenance using Perl scripts found in the repository are needed for adding new help texts.

• Since current help system is stored within the source repository, anyone needing to make changes must be a project committer. This seems rather burdensome to new volunteers who would like to participate in this area.

• Because the Online Help is "homegrown" and difficult to fathom, it will always need special attention. So, it is not very sustainable in its current form.

Moving Forward

Since we're off to a fresh start, this is what we ought to do with the help:
(see also the following mail thread: http://markmail.org/message/tl5lsy4cxaa3s6lx)

Help File Source Format

• move to a standard format (DITA was proposed)
• simplify the build process
• create an easy authoring workflow to enable participation

...