Recently we asked for ideas on the OOo mailing lists how we can improve the installed Help of StarOffice and OpenOffice.org. One good idea was to add more links that point to external documents written by the community.

Currently, at the end of many Help pages you find "Additional information" or "See also ..." sections. These links stay within the installed Help system, or they link to portal pages like documentation.openoffice.org which will work without "page not found" errors for quite a time.

Given the ever changing availability of external documents with regards to version, operating system, and language, as well as their Web locations, a database approach seems to be appropriate.

Now we want your feedback about the following proposal

a) the Help Viewer already knows about the operating system, version, and language of the installed Help. Additionally, the user will be able to select additional languages to read external documents that are only available in those languages. And the user will be able to disable the Web search for additional documents, and to redirect the search to a folder on the local file system.

One idea is to offer a drop-down list box with the main languages. The current Help language already has a check mark by default, and the user can select more languages.

Enable external Web Help:
  (none)
v english
  german
  french
  ...etc...

Choose (none) to disable Web Help from the Internet.
An additional check box "locally installed documents" can be enabled to display links to documents that are stored in a given folder on the hard drive. Every user can store own documents here, which must contain some meta information to be shown at the right location of the Help.


b) The current Help page gets some additional entries in the "More Information..." or "See also..." section.
These new entries are visible only if Web Help is enabled and if such help is available.
If the Web Help is enabled and if the current shown Help page contains a link to the new Web Help feature, then the Help Viewer connects to the server over the Internet.

The Help Viewer sends the following information:
- the current Help page
- the current version of the Office software
- the current operating system
- the selected languages for external Web Help

The server evaluates this information.
If any Web Help document is available for the current page (topic), version, operating system, and language, the respective link or links are returned. These links will be shown in the "See also..." section. The user can click the link to load the external document.
If no suitable document is found, the server returns the following text:
"For this Help page we have no external document at this time. You may consider changing your language selection at Tools - Options - ...etc... Visit documentation.openoffice.org if you want to write an external Web Help document for the current topic."

The server evaluates the Help pages and languages for which Web Help was asked. These data will be published periodically. The information helps to improve internal and external Help offerings.

c) There is a database running on the server. The community maintains the database. When for example a Language Project has some new documents, the respective links will be added to the database. There might be a Wiki to simplify adding and editing the hyperlinks together with meta information about visible text, language, version, operating system. A script will update the database based on the Wiki information.


This is what I propose. Now please let us discuss this concept. Give feedback if you want it in such a way and if you think it can be done. Then we need to find some community members who really do all the work.

What do you think?

[First update:]

In a mail exchange I got the chance to give more precise ideas on some topics:

in my first idea about the database and Wiki it looks like this:
the database has records like "help page ID", "OS", "language", "version", "link to document"
the Wiki is only to enable everyone to add a new document to this database, even without SQL and database access permissions. Just enter the data to a Wiki, which is a skill most people already know, and then a script will transfer the Wiki data to the database (may be after a moderator has checked that the document is really an OOo Help document of any value - but if it is not, then normal Wiki community social control will remove an invalid link soon)
Database records:
"help page ID" can be the unique path and name of the guide file from the installed OOo Help. Example "sharedguidekeyboard" for a link that will be visible in the "See also..." section of the file shared/guide/keyboard.xhp.
"OS" the operating system info seems to be valid for some help documents, as for example the UNIX printer and fax and font guides which are of no use to a Windows user.
"language" is the language of the linked document.
"link to document" is the full http address of the document. In some cases this would not link to a document but to a Web page that the submitter wants to be shown first, for example with a copyright statement or an advertisement/promotional page. We should be open to such a redirection, but of course this can be discussed.

the proposed system should be flexible enough so that no one must split up or change any document that already exists. And it is open to any reasonable amount of additional documents that other users supply.

the meta data comes into account when you do not use a link as stated above, but when you just have a collection of Help documents all inside one local folder.
In this case we need any index data to quickly determine to which OOo Help page a certain document belongs.
As the user-supplied additional Help documents in that local folder can be of any valid type (OpenDocument, PDF, HTML for example), it may take too much time to read the meta data from inside the documents' info. We would need one index file and a method to fill the data into this index file. Or we must define a filename mapping of the data, so a document with the name shared.guide.keyboard.all.US_en.odt in that folder can be identified easy to be linked to the sharedguidekeyboard Help page, to be valid for all operating systems, to be in US english language, and to be of OpenDocument file type.