Application Help

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

Current Situation and Issues

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:

• when non-English versions are built, the English content inside the help files is replaced by the localized content stored in a different module.
• the help files are XSL-processed to produce the full text search index
• the help files are XSL-processed to extract the extended tips displayed in the UI
• the help files are XSL-processed to extract the keyword index

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.

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.

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.

Moving Forward

Since we're off to a fresh start, this is what we ought to do with the help:

Help File Source Format

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

Help Viewer

• use current technology (HTML 4+, CSS4, bells and whistles)
• don't let the user decide on which route to find info (TOC, index, search), give a search input field and let the help find the best results
• fix the search engine
• integrate the help viewer with the UI

Help Content and Structure

• Limit help content to instructions, and some basic concepts
• Show reference information ("enter your name in this field") where it's needed, on the UI, side-by-side to the element it refers to. For that, we need rich fornatting in "bubbles" (extended tips).
• Reduce the amount of offline help content and allow to expand to online sources
• Allow rich media in help files