Application Help Content Management and Delivery

Overall

OpenPetra currently does not have application help (usually launched with the 'F1' key).

The goal of this project is to set up the technical platforms for editing, creating and publishing of the application help with the aim of having the application help output in the so-called 'WebHelp' format. Writing the content is not part of this project (with the exception of the creation of limited content to prove that the technical platforms work as desired).

The technical platform should be Confluence or Calenco, as mentioned in the section 'Tools for Evaluation', for the major parts of what we want to achieve with this project.

Requirements

The requirements listed here are in addition to what is listed in the section 'Requirements'!

Key Requirements: Met Automatically by DocBook's 'WebHelp'

The key requirements for the Help system we are aiming to have that is that it needs to be able to run in a web browser, run cross-platform (Windows, Linux and Apple OS X), must have a full-text search, and translations must be possible.

Also, the help system must be accessible "online" and "offline".

• With 'online' we mean that the Help system can be accessed via a website, like the 'Calenco' documentation which is found here). The advantage of this is that the content can be kept highly up-to-date.
• With 'offline' we mean that the Help system needs to work totally without any Internet connection, which is not easy if one wants a full-text search ability and one does not want to install a local webserver on the user's machine, which would be overkill just for achieving that. WebHelp has that offline capability even for the full-text search.

The application help output we have chosen with DocBook's 'WebHelp' meets all those key requirements.

URL Part That Specifies a Help Topic Must Remain the Same if Content is Modified

The part of the URL that opens the correct help article in the web browser when the user presses the 'F1' function key must not change, e.g. it must stay the same when new help topics are added or some help topics are deleted. The part of the URL could be an ID or a string identifier, for instance. The reason for the 'static-ness' is that the ID's (or whatever identifies the article uniquely) need to be 'wired up' to the F1 handling code inside the OpenPetra application so that the correct Help page is opened on user request, no matter how much the content in the help system has been changed since that 'wiring up' took place. This is needed esp. for the 'online' Help access, but could be needed for 'offline' Help access as well if one wants to publish offline Help content updates without the need for updating the 'wiring up' in the application's binaries.

Note: By default the URL Parts that are generated with WebHelp are NOT static and change when new help pages are added between help pages!

Optional Features

The requirements listed here are in addition to what is listed in the section 'Optional Features'!

Users Can Leave Comments on Topics

Integrate a User Comment Form as found here ('Post a Comment on xyz' section of the web page).

Expected Outcome

General

Attempts to realise the individual requirements (and possibly the optional features) listed on this page, as well as the ones here, should be made with both Confluence and Calenco.

Once this is done with both products, a write-up should be done of the 'pros' and 'cons' of each product.

Based on the write-up we will make a judgement. We are then planning to use our favoured product for the purposes of authoring application help for OpenPetra.

All requirements must be met, if optional features are present then this is a bonus.

Assessments

The WebHelp output will be compared with the electronic user guide output from the same source(s) (wiki pages, DocBook document(s)). The expected differences will be looked at and any unexpected differences or content that should/should not be present in the WebHelp will be checked for.

ChristianK and MatthiasS will assess the WebHelp output for its suitability as OpenPetra's application help.

Other

WebHelp Output Customisation

The default WebHelp output is pretty good. What we would want to customise is exchanging of the DocBook logo with the OpenPetra logo and perhaps have some CSS tweaking done for the layout.

DONE by ChristianK

Optional/Bonus: Integration into OpenPetra ('F1'-Key Hookup)

This will be done in tight co-operation with ChristianK who already has the concept in his mind for the realisation...