Table of Contents
Requirements for an Extensible Help System |
Abbreviations |
1. Motivation |
2. Stake holder |
3. The environment |
Extensions |
Help |
4. Requirements |
Sun Release Engineering |
Externals |
Internal |
Sun Documentation Department, Sun Globalization Group |
OpenOffice Contributor |
Thanks |
by Andreas Bille, Sun Microsystems, Inc.
Sun Sun Microsystems, Inc.
XML Extensible Markup Language
GUI Graphical User Interface
OHC OpenOffice Help Content
HPE OpenOffice Help Production Environment
UNO Universal Network Objects
SDK StarOffice/OpenOffice Development Kit
ADI Application Documentation Interface
API Application Programming Interface
OpenOffice product development currently focuses on the development of a component architecture, in which OpenOffice serves as the framework for – possibly interdependent - extensions adding new functionality to the base OpenOffice package.
Due to this new focus a new problem emerges, namely that to purvey the extension together with documentation of the offered functionality, which should integrate as smoothly as possible into the native OpenOffice help system.
This document describes and organizes the multitude of aspects related to this basic requirement. It is a initial version, not a definite locking up of wanted features. No attempt to define technical solutions is made.
There are several „institutions“ coming into contact with the current OpenOffice help system. The four most important „traditional“ ones are:
The documentation department of Sun, producing the documentation of the OpenOffice base package in the mother language English. The original format of the documentation is a Sun proprietary XML-format, with filename-extension “.xhp”.
The globalization group of Sun. This department is responsible for many of the available translations into other target-languages.
The release engineering of Sun, responsible for the build process building from the many thousands of files both the “.xhp”-files in in several dozens of other languages and the language specific databases and packages, which are used during the installation process of OpenOffice.
The quality-assurance of Sun, responsible to ensure that functionality works as described in the documentation, and both coincide with the specification of the respective feature.
Sun external OpenOffice contributors translating help content and building help installation sets.
Due to the new development focus we now have two additional groups of people contributing documentation via extensions of OpenOffice:
Developers of Sun Microsystems, Inc., short internal. These developers typically specify, design and code the extension. They are embedded in the larger software development process applied within Sun. Typically, they do not write documentation, but only the feature-specification becoming the basis for the work done by the documentation department.
Developers, Quality Assurance etc. external to Sun Microsystems, short externals. These externals are not connected to the software development process within Sun and in reality may be backed by some sort of different process by themselves – however, there focus is to deliver extensions containing documentation.
It is then a requirement to make the offered documentation production environment of OpenOffice so flexible, that it can be adapted easily to processes differing from the Sun process.
An extension is installed and removed using the extension manager of the OpenOffice base package.
It has installation requirements expressed trough the reference to specific versions of OpenOffice or trough the requirement that specific versions of other extensions are already installed. These requirements do exist, because an extension uses or “references” existing functionality of the base package or of other extensions.
Removal of an extension leaves OpenOffice in the same state it would have without installation of that extension.
An extension might have a GUI or it might be a component working in the background, not demanding any user interaction trough dialogs, menu entries or tool bar. There are currently no style guides available defining the main points in the user interface of OpenOffice, which an extension might address for enhancement.
After installation an extension works in a certain environment – for example it might add to the functionality of OpenOffice Writer only, or in addition to the functionality of OpenOffice Calc. That is, an extension might run in different contexts – once more, the “application-context” might be one example only. Other contexts could be “internet access available”, “unnecessary, but useful extension supporting own functionality not installed” etc.
An extension is localized and should conform to accessibility standards.
The main help page offers the following functionality:
In the left panel of the help window there is a tab page containing first a content tree, organizing selected documents of the OHC in a hierarchical view. Despite the appearance of that view the OpenOffice help content is not organized as a book, that is, there is no natural consecutive ordering of the individual pages. Not every page of the OHC can be found in that tab page.
Second there is the Index tab page. This tab page presents a two level index of keywords. Every keyword represents a link, clicking it shows the corresponding content in the right side of the OpenOffice help view. The index is application specific, the user can switch between different application specific indices using the list box listing the OpenOffice help modules above the tab page in the right panel.
Third, the Find tab page offers an also application specific full text search. There is the possibility to search in headings of OHC only and/or to search for full words only. The user can search for an arbitrary number of terms in one search.
Fourth, the Bookmark tab page let the user add references to selected pages by right clicking in the content view on the right page and selecting the menu entry “Add to Bookmarks”. The user is then invited to enter a title for the bookmark.
The user interface of OpenOffice offers additional help-connected functionality.
There are two sorts of tool tip help available – the “Short Tips” and the “Extended Tips”. The user can switch between the different versions ( or suppress them ) by corresponding entries under “Tools->Options->OpenOffice->General”. In addition, extended tips can be shown by pressing the key combination “Shift-F1” or selecting the menu entry “Help-What's This?” and pointing to an element.
Under the same entry on the settings page the user can activate or reset the help agent, which automatically starts if the user starts a task that might require some assistance. Clicking the help agent – a small window in the lower right corner – then displays the corresponding help page.
Also the user can select the formatting of the help content appearance using different styles – all these styles reflect different modes of accessibility.
The viewer used to display help pages is the OpenOffice Writer/Web in read-only-mode, which is able to format HMTL in version 3.2.
It makes sense here to define shortly, what I mean with the below often used notion “documentation” - it includes any information available trough the described interfaces of the OpenOffice help system – particularly short tips, extended tips, OpenOffice help content (OHC), content tree, indices, bookmarks, description of help agent starting tasks, topics ( see below ), “see-also”-links ( see below ), description of dynamically extendable pages ( see below ). Depending on the context of the use of “documentation” it sometimes means some part of this list.
Many requirements can simply be derived by a closer look at the discussion under point three. The – in my eyes – most prominent one which cannot be derived, is formulated by
The tooling of the HPE must be fast enough, to allow the generation of help installation sets for many dozens of languages, generated from several thousands of files in a short time frame. Especially, experience has shown, that it is not possible to produce the help installation sets in an edit-compile-link-cycle, in which the information every file contributes to indexes etc. is derived during a compile-step. This is largely due to the extreme number of processed files and the corresponding load time of the help tooling. The current solution therefore relies on a batch process, in which all of the compile and the link cycle are processed in one call to the help tooling.
Otherwise, it is easiest to begin the discussion from the point of view of
They need to produce an UNO package containing the documentation for their feature. This includes the requirements, that an external must be able to produce the documentation, UNO packages must support documentation as part of their structure, and the extension manager must be able to install an deinstall documentation.
Lets assume, that their component has a GUI. There exists then the need to correlate the different controls of their dialog, tool bar button or menu entry with the documenting text on different levels – tips, extended tips, help page. The correlated text for itself might depend on the environment, in which the extension runs – that environment must be determinable by the extension. An example for such a context would be the above mentioned “application context”: a translation supporting extension running in both OpenOffice Calc and OpenOffice Writer might want to show different tips for a control in a dialog if either Calc or Writer are the currently active application, because the text must be different for text translation or number formatting.
As the number and nature of possible environments cannot be determined in advance, any simple static solution might fail – it must be possible to determine dynamically the identifier, which references the relevant part of the documentation.
Also, there is then the requirement to make such identifiers unique across all extensions – which can, however, be handled because extensions must have an unique name. In essence, the external must be able to correlate dynamically determined identifiers to different sorts of help text.
However, the SDK also contains a dialog editor. Many applications will not have the requirement to change the documentation depending on the current context. It is therefore also a requirement, that for such less elaborate usages there exists a simple mechanism allowing developers to coordinate statically assigned ( to controls ) identifiers with documentation. This simple mechanism must be made available trough the dialog editor of the SDK.
OpenOffice itself cannot really know, which control in a dialog is currently active. That is, OpenOffice can signal the component, that help is requested - to this end it must first of all be able to determine the currently active component. The rest is responsibility of the extension. If a tip or extended tip is requested for a control, the component must calculate the identifier of the requested help – it then either has to show the requested help text in a tool tip or it must trigger OpenOffice functionality to start the help viewer. The component must feed OpenOffice with all information needed to correctly point the help viewer to all relevant parts of the documentation.
Own help content must support images, available in localized or accessibility conforming form.
An extension must be able to add situations which trigger the appearance of the help agent.
While the discussed parts are mostly related to installation, there is also the requirement that after deinstallation all links to documentation of that extension should be removed – as for contents tab page, the keyword index, the full text search and all bookmarks. However, below I will show, that it might not be possible to fulfill this requirement generally.
Special consideration is needed for the relation of new documentation to the existing documentation, delivered by base OHC and the documentation already installed by other extensions. We can discuss the following points:
New documentation should be able to modify the contents pane. The contents pane is currently an ordered tree – so any reordering might clash with the reordering other extensions try to superimpose. OpenOffice needs to define some resolution mechanism.
An extension might define an insertion into lower planes of the tree, saying that a new node must be inserted directly before or directly after some existing node.
Or the insertion of new nodes is a task left to the OpenOffice help system – we could define for instance a special node “Extensions” and every entry is made under that folder.
Full text search must be able to find new help content. The full text search is specific to OpenOffice applications.
An extension must be able to add to the keyword index. The keyword index is specific to OpenOffice applications.
Suppose, an OpenOffice Calc add-in adds a new function – “add-ins -> functions” is a separate entry in the existing keyword index of OpenOffice. The natural place for the documentation of the new function would than be the page already describing functions available in OpenOffice Calc.
We can discuss several solutions for that dilemma – the following is meant to be a list of suggestions for requirements, resolved in the final version of this document:
a). A new, similarly written keyword index entry, which appears directly beside the old entry, for instance named “add-ins->functions-from-extension”. No new requirement.
b). The extension is allowed to turn the keyword index entry into a three level entry, having in the third level links to both the old documentation and to the documentation of the new function. The OpenOffice help system has to support three-level-entries. Otherwise, an extension must be able to add to the keyword index.
c). We invent a new “See Also”-linking mechanism, which belongs to OpenOffice documentation. The extension must be able to foist the documentation of the new function to the “See Also”-link of the existing documentation of Calc add-in functions. “See also” - links would form a part of the ADI – once published, they must be stable in all following OpenOffice versions.
d). We allow direct modification of the help page describing the add-in functions. However, a closer look at that page shows that it has a special construction – a header, the function descriptions and a trailer. An extension would like to add to the descriptions, so any naive approach is doomed to fail, especially the simple approach to add new content simply to the end of the page. Instead, there is the requirement to unitize help pages – in our example into header, description and trailer – and to be able to generate the original page dynamically, namely from the header, the description of all installed add-in functions, especially also those contributed from the extension, and from the trailer of the original document. Additionally we require than a reference mechanism allowing an extension to add documentation to the topic “Calc add-in function descriptions”. This reference and the corresponding mechanism would be part of the ADI.
As discussed above, there is currently no style guide available defining the most prominent places in the user interface available for extension.
Such a style guide could, for instance, define, that extension specific settings should be made available trough a special panel, which the extensions assigns to the standard OpenOffice options dialog available under menu entry “Tools->Options”.
Suppose we would have such a style guide, one would be able to identify pages probably in need to be extendable in an extreme manner. Think, for instance, every extension supplemented settings panel will appear under a new entry “Extensions” in the options dialog. The corresponding help page of that dialog will then contain a link to a special “Extensions”-page, which will either contain text or links to text describing the settings of that extensions. This “Extensions”-page must be generated dynamically and we must have a mechanism allowing extensions to mark content to be added to the topic “Extension Settings descriptions”.
In essence, this is the same requirement as under d.). of the last point.
Think of a component, which needs correct proxy settings to work. That component will not describe that settings on its own, but might want to refer to the existing documentation. Changes in the OHC might then break that reference – which cannot be allowed. The ADI of OpenOffice documentation must be stable in the same way the API is stable.
However, as already adumbrated above, this does not mean that the implementation specific identifiers of documents must stay stable – we do not want to make implementation details part of the OpenOffice interface.
To illustrate this important point, imagine, that the descriptions for feature A and feature B are in one version of OpenOffice found on one page, in a second version on two pages. Imagine that two extensions refer to that page of the first version using its implementations specific identifier, the first extension because of the description of feature A, the second because of feature B. It is then impossible to ensure that both usages of the document identifier in the earlier version of OpenOffice stay intact in the later version offering two pages, that is, point to the correct documentation – we do not need technical intactness, but semantic integrity.
Instead, an extension must not refer directly to identifier of documents, but rather to themes or topics. For feature A we then have topic A, for feature B the topic B and, as long as documentations of that topics are available in different versions of OpenOffice any reference to that topics would then be resolved correctly, no matter how the OHC might be reorganized – the documents, in which the topics are described, can be resolved at runtime. There exists then the requirement, that a database mapping topics to pages is maintained across all versions of OpenOffice.
Also, the “topic-set” offered by OpenOffice documentation – which is simply a categorization of OpenOffice documents – must form a stable interface to that documentation. This makes sense, because an extension referring to the topic “proxy settings”, probably will not work anymore if OpenOffice has no need for documentation of “proxy settings” in later versions.
Additionally, because extensions are interdependent, extensions must be able to define topics for their documentation on their own – these topic sets would than belong to the stable ADI of that extension – and could, to figure out the possibilities, even contribute to a classification of extensions which might be usable in a web shop, for instance.
Because the deinstallation process of extensions in OpenOffice does not automatically deinstall all dependent extensions, there exists the implication that references to topics of the deinstalled extension made by the dependent extension get broken. This is not an error in the concept, but a consequence of the deinstallation mechanism.
Now breaking my promise not to speculate about a possible technical implementation, I mention that some of the mentioned requirements concerning the relations between new and existing documentation might be addressed by a careful and moderate advancement of the concept of the keyword index – in fact, some requirement could be fulfilled without any advancement, but reduce to the postulation that keywords do belong to the stable interface of OpenOffice.
Immediately in mind comes the second index available in OpenOffice, the full text search. Any extension must be able to place links in its documentation which are resolved by a full text search. The search result might be presented either by a specially formatted help content displayed in the right pane of the help viewer. Or the search result might be displayed by showing it in the Find tab page in the left pane. I would prefer the first solution, because the second would make the user interface “turbulent” - the user not normally expects that pressing a link in a document can alter the shown tab page on the left side of the help viewer.
Built in OpenOffice help content has a proprietary XML format – recognizable by the ending on “.xhp”. Those files are part of the OpenOffice installation package and will be transformed to HTML during runtime. The convenience of this is, that documentation written in that format automatically shares its formatting with the OpenOffice help content. Additionally, the support for accessibility would work using the standard OpenOffice mechanism.
For documentation written in other formats – for instance Java Help, HTML – there is currently no connexion in OpenOffice. It might be a requirement to support such nonnative formats. It might depend on the particular format and its support in the HPE, which sort of information an external must add to its extension if nonnative documentation should be supported. However, I consider this to be a highly technical point, only to be addressed if demand for this exists.
I would like to mention that there is an export filter available turning OpenOffice 1.1 into a help authoring tool allowing to read and write “.xhp”-files directly with OpenOffice. This help authoring tool must become part of current versions of the SDK, possibly in the form of a documented extension.
Internal share all requirements with externals. However, they will not produce documentation on their own, but the Sun documentation department will do this for them. They must have a build environment, in which documentation for their package is produced together with that package – normally this means, that in CVS the documentation belongs to the same module. Release engineering probably must change the current build environment to support this – also a highly technical point of view.
No special requirements. Some requirements might imply that a newer version of the current file format has to be invented.
They are herewith invited to contribute their requirements and wishes to the discussion.....
Thanks to Stephan Bergmann, Hans-Joachim Lankenau, Lars Oppermann, Frank Peters, Jens-Heiner Rechtien, Jürgen Schmidt, Kai Sommerfeld and Tom Verbeek, all Sun Microsystems, Inc. for their contribution to this paper.