OpenOffice.org Help TNT: Tips'n'Tricks that somehow didn't make it to the help (yet).

As you might already know, OpenOffice.org runs a user feedback program, aka improvement program, to collect data about the normal user's use of the OOo software. This is an opt-in program, and the user is asked if he wants to take part in the program the second time he starts his new installed OOo.

On the User Experience web page for the User Feedback Program (1), we can now see some more results of how many users open the installed Help and how they do this (2).

This is quite exciting, as it is the first time Help authors get some feedback "with the users' feet". We see how many users open the Help menu, or in which dialog boxes they click the Help button most often.

However, it is not easy to interpret the big Calc document with all the results (3). Mouse click events are named by developers who never thought about using names that can make sense to the public. The menus and dialogs are named to conform to internal code dependencies, not to fit the visible user interface. I do not claim to understand most of the results, so take the following data just as my first approach to interpret what the data might possibly mean. All numbers are to be interpreted as relative to each other. The sheets are ordered by COUNT, so the events with the most counts of user interaction are at the top. Searching the sheets for "help" returns the following list of observations:

Observations in Writer

Total use of "Save" (by menu, toolbar, or keyboard) is about 2.5 million times in the data, so we possibly see data for about 2 million documents (given that some users only save once, and some save often).

The main Writer Help window gets quite many click events, about 1 million times. That can mean that users love to browse and read the installed Help pages, or it can mean they click often and still find nothing of use to them.

The Index tab page of Help Viewer gets clicked about 50,000 times.

The Find tab page counts about 16,500 clicks, and the Contents tab page gets 4,500 clicks.

So the average user clicks inside the Help pages about ten to twelve times before he leaves the Help Viewer. Too bad we don't have a feedback whether the average user is now happy or sad.

The Writer dialog boxes where the Help button was called most often:

1. Word Count
2. Print
3. FontWork
4. Options
5. Spellcheck
6. Find & Replace
7. ASCII Filter Options
8. Special Characters
9. Extension Update
10. Printer Setup

From a user experience point of view, it would be a good idea to minimize the use of Help.

So the Word Count dialog should get improved by some text that explains what counts as a word, for example. I guess that information is missing, and users therefore have to click the Help button. Unfortunately, that information is also missing in the Help page. So this is the first thing to improve!

Observations in Calc

For Calc, we see about 1.8 million "Save" operations, so let's say data is for about 1.5 million spreadsheets. The Calc Help was called about half as often as the Writer Help.

The Calc dialog boxes where the Help button was called most often:

1. Function Wizard
2. Delete Contents
3. Find & Replace
4. Print
5. Format>Cells>Numbers dialog
6. Options
7. Rename Sheet
8. Conditional Formatting

Observations in Impress/Draw

The Impress and Draw Help were each called about one tenth as often as the Calc Help. Either these applications are very intuitive to use, or users really do not expect to get some Help here.

The Impress dialog boxes where the Help button was called most often:

1. Presentation Wizard
2. FontWork
3. Slide Design
4. Slide Show

The Draw dialog boxes where the Help button was called most often:

1. FontWork
2. Format>Text (for text in a text box)
3. Format>Line
4. Options

With these data, Help authors now know where improvements of the Help system are most effective and might be most wanted.

(1): http://wiki.services.openoffice.org/wiki/User_Experience/OpenOffice.org_User_Feedback_Program

(2): http://wiki.services.openoffice.org/wiki/Tracking_results

(3): http://wiki.services.openoffice.org/wiki/Image:OOo31_Usage_Feedback_Data.ods

Clayton just posted the following message on the dev@documentation.openoffice.org mailing list.

Hope to see you all there to chat about documentation at openoffice.org:

Hi everyone.

I've registered an IRC channel for the docs project.  This is a public
channel, and open to anyone to join.

The channel name is:

  #openoffice.org-docs

Feel free to pop in an chatter anytime.

I've added it to the IRC channel list here:
http://wiki.services.openoffice.org/wiki/IRC_Communication

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.