CogentHelp Walk-through

This walk-through demonstrates some of CogentHelp's features, by showing you a few of the steps involved in using it to create a context-sensitive help system for a sample applet. The walk-through is best viewed in a full-screen window.

Back to the CogentHelp page

The sample applet

We start with a sample applet called PictureWorkshop, for which we've created a help system using CogentHelp. PictureWorkshop lets you draw a variety of simple shapes by operating various controls. It's not a terribly useful applet, but it will serve to illustrate the process of creating help topics which explain the functions of each of the controls.

When we click on PictureWorkshop's Help button, this brings up the partly-completed help system in a new window (see below). This window serves a dual purpose: it's the help window that the end user of the applet will see, but it also hosts CogentHelp's authoring interface. For the rest of the walk-through, we'll put ourselves in the help author's shoes — and start by noting that since we're using the same interface to create the help as the end user will use to view it, there should be no surprises down the road as far as how it will look when we're finished!

The help window

The help window features an expandable table of contents on the left, and some standard navigation controls at the top. In the lower part of the window are some additional controls, which are part of the authoring interface. When we've finished authoring the help system, we'll switch it to end-user mode, and these buttons will no longer appear.

The table of contents contains two types of topics: "General" topics, which give high-level information about the application, task-oriented help, etc.; and "reference-oriented" topics, which describe the functions of individual windows and widgets. General topics are written by hand, using our favorite HTML editing tools; reference-oriented topics are generated automatically by CogentHelp, using text that we provide, in the form of "help snippets".

Help snippets

Now, let's look at how help snippets work. If we click on the Edit button shown in the "Color" topic, this brings up a window in which we can edit the help snippets for the Color widget (the list box in the applet which contains a list of color names). CogentHelp maintains a set of these snippets for each widget in the application, and uses them, together with a set of template-like objects called exemplars, to generate the help topic for each widget.

Each of the help snippets contains a different type of message concerning a widget. The first one is simply a label to be used to refer to the widget in the help system (this may be different than the label shown in the interface in some cases, or there may be no label in the interface). The second snippet is simply a brief description of the widget's function. The third is an optional elaboration, which may be a paragraph or so of further explanation. The fourth and fifth describe conditions under which the widget is enabled, where this is appropriate, and how to enable it if it is disabled. Finally, the last snippet simply contains a list of hypertext links to other relevant help topics.

The first thing to notice about the snippets is that they are written in HTML — this lets us enter anything from plain text, to bold, italics, and hypertext links; to audio, video, and whatever else is expressible using HTML. The other main thing to point out is how "syntactic frames" are used to guide the help author in writing snippets — for example, the second, "Short Description" snippet should fit in the frame "This object ______." (so an syntactically appropriate value for this snippet might be "determines the color of the picture").

The main benefit of authoring help snippets, instead of monolithic, unstructured help topics, is that it lets us concentrate on the content of the help system, instead of the nitty-gritty details of formatting, linking, etc. — these are handled automatically, and with perfect consistency, by CogentHelp. The use of syntactic frames with snippets also creates possibilities for text reuse — for example, when CogentHelp generates a help topic for a widget, it capitalizes the Short Description snippet and places a period after it. If we decide at some future point to change the exemplars so that, say, a subject phrase like "This item" is placed before the Short Description, we will know that we can do this without having to rewrite all the Short Descriptions. The same goes for other, more mundane changes to the topic exemplars, such as changing how the label is formatted — global characteristics of the topics can be changed independently of the content, which resides in the help snippets.

Besides edit fields for the snippets, the Edit Snippets window also contains a handy item which can be used to generate a hypertext link to any topic in the table of contents (either hand-written or automatically generated). This simply produces the correct syntax and URL for the link; we can then copy and paste it into any of the snippets.

Consistency checking

So, we've seen how CogentHelp makes it easier to create reference-oriented help, by saving us from having to perform much of the drudgery that this normally involves. However, CogentHelp has some other important features, of which perhaps the most important is the ability to check the consistency of the reference-oriented help with the application being documented. If we click on the "Check Completeness" button in the help topic window, this displays a report that lets us know how we're doing.

CogentHelp tells us about any "obsolete" widgets in the help system — ones for which we've created help topics, but which no longer exist in the application. We'll probably want to delete these topics, or else talk to the developers about whether these widgets might reappear in the near future. CogentHelp also lets us know about new widgets for which help topics have been created, but for which we haven't actually entered any help snippets yet. This information helps us to make sure that our help system actually corresponds to the current version of the application we're documenting — this can be particularly useful if we want to start creating the help while the application is still under development (something that help authors would probably avoid otherwise, for fear of having to do repeated manual consistency checks).

The information that CogentHelp uses to perform consistency checks is passed from a CogentHelp client object, which is embedded in the applet, to the CogentHelp servlet, which is embedded in the web server. The client object knows how to tell the servlet about the widgets in the applet (once we register them with a few lines of code), by encoding information into the URL which is used to request help from the server. The client object also prints warning messages to the Java console to let us know if there are any widgets we've forgotten to register.

The CogentHelp servlet contains the help-topic generator. It is built using the Java Servlet API, which lets you create "mini-servers" that can generate HTML and maintain state between requests much more easily than CGI scripts. The servlet manages the help snippets for each widget, as well as the table of contents. It generates help topics in response to requests — the request URLs may encode either widget information from the applet, or updates to the snippet text from the authoring interface.

Creating help topics

One "side effect" of the protocol CogentHelp uses to pass information from the applet to the servlet is that we can create reference-oriented help from scratch simply by using the applet. If we open the Set Border Width window, for which we haven't created any help yet, and click the Help button, CogentHelp will take an appropriate action: when the servlet decodes the help request and finds descriptions of a window and some widgets for which it doesn't have any snippets, it will create new help topics and snippets for each of the new items and add them to the table of contents — we can then proceed to edit these new snippets.

Another thing we'll want to do with these new topics is to move them around in the table of contents (TOC) structure, since CogentHelp has just stuck them on the end. To do this, we can click the Edit button below the TOC in the help window to bring up the Edit Table of Contents window.

Editing the TOC

This window lets us move the nodes in the TOC around as we see fit, without disturbing CogentHelp's record of which widget topics exist. So we could move the new BorderDialog topic right, putting it under the Reference heading along with the other reference-oriented topics.

We can also use this window to specify how hand-written "general" topics fit into the TOC, by creating new nodes and specifying the URLs and images associated with them. We can also move them around however we wish — including the possibility of interspersing them with the generated topics.

So, CogentHelp not only makes it easy to create reference-oriented help, it also gives us lots of flexibility to integrate this with our hand-written topics. And it helps us to maintain consistency by passing information between the application and the help server. Another feature of this information-passing capability, however, is that it lets us generate help topics which incorporate dynamic information reflecting the current state of the application.

Dynamic help topics

You may have noticed that the PictureWorkshop applet contained a couple of radio buttons, labelled Light and Dark, which were disabled. If we were using the applet and wanted to find out why they were disabled, we might go to the help topic for the Dark radio button to search for clues. We would then see a message telling us that it was disabled because of the current selection in the color list box.

This kind of help topic, whose contents change according to the current state of the application, is possible because one of the bits of information that is passed to the help server about each widget when a help request is made is a string representing its current "state". In the default version of CogentHelp, this string is simply a "Y" or a "N", according to whether the widget is enabled or not. Here, we are actually seeing the result of a sample CogentHelp customization, whereby when a widget is disabled, the name of the currently selected color is passed, instead of just a "N". On the server side, this enhanced information is used to generate an informative message.

Customizing CogentHelp

This customization required two steps. The first was to modify the CogentHelp client object to pass the enhanced state information — this simply meant overriding a Java function which is used to compute the state string for a widget (a task that we, as help authors, may or may not know how to do, but which will be a piece of cake for our friends, the applet developers). The second step was to create a new exemplar on the server side, which knows how to use the enhanced information when generating the relevant piece of help text. If you're interested in seeing the source code for this new exemplar, click here. But before you do that, you might want to learn more about CoGenTex's Exemplars framework, including the Exemplar Definition Language (EDL) which is used to write exemplars, by clicking here.


As we unlace our help author's shoes, let's review some of the unique features of CogentHelp that we've seen, as well as a couple we haven't mentioned:

  • It automates much of the "drudge" work involved in creating reference-oriented help, letting us concentrate on getting the content right;
  • It helps us to maintain consistency between the help and the application we're documenting;
  • It gives us flexibility in how we incorporate hand-written materials into the help system;
  • It can be customized in various ways, including the way in which it generates dynamic help messages according to the current state of the application;
  • It allows us to deploy our help system, as well as the application itself, on an intranet or over the Web;
  • It supports integration of standard web search engines.

Thanks for taking the time to check it out!

Back to the CogentHelp page

(c) 2016 CoGenTex, Inc. All Rights Reserved.