This is the planning page for the OO application help (aka online help, despite not being "online").

Current Situation and Issues

Structure

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

helpcontent2
   helpers           these are required or helpful for building the help content,
                     some files are called by make, some others are obsolete
                     xmlhelp.dtd  > the DTD for the help XML format
   source            this is the actual content
      auxiliary      this are help relevant files that are not content
                     *.tree > the definition files for the help viewer table of content
                     *.xsl > transformation scripts used to process the help files
                     $LANG/*.css language dependent files for controlling the HTML output
                     $LANG/*.cfg language dependent config files (legacy)
      text           the help content files, organized by modules (rather awkwardly, see below)

The help content files are in a home-grown XML format described in helpers/xmlhelp.dtd and are processed in various ways when the help is being built:

The final help set consists of sets of various files (jar, cfg, tree, xslt, database files) for each module. A module in the help does not exactly correspond to an application module (Writer, Calc, Impress) for historical and technical reasons. The schart module is present in the help although there is no standalone Chart application. There is no sdatabase module, although there is a Database application. So: it's a mess.

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

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)

Ongoing Maintenance of Current Help

Helpcontent2 in its own svn area (a copy)

A Means of Analysis of Current System/ Files

Currently, there is an xslt file provided for the help system, so individual help file structural correctness can be ascertained. However, there is no overarching analysis tool available  for the determining the correctness of the combination of various IDs in place and their cross references. Without some mechanism in place, adding new entries or editing existing ones is nearly impossible. Before we can move to a new system of any kind, it vital that some structural analysis be made on the existing help system. Porting the help files into an XML database in some way might help in this. This needs discussion and expertise to move forward.

Migration to a New/Different System – questions/challenges

Help File Source Format

Help Viewer

Help Content and Structure