Boston Broadside
September/October 2001
Vol. 59,  No. 1
    Newsletter of the Boston Chapter of the Society for Technical Communication
   

Inside

Copyright © STC Boston 2001
 
     

Communicator's Toolbox

Cataloging Information Aids Help Development

By Alfred Barten

Context-sensitive help systems often need redundant placement of information. This ensures that the information is seen by visitors who enter and move unpredictably through the system. Redundant placements take the form of descriptions, explanations, warnings, and the like that amplify other subjects. In software documentation, for example, some candidate subjects include the purposes of screens and tabs, the effects of selected options and significant functions such as Delete, and reminders of required access permissions and prerequisite steps or conditions.

You can save development time and promote consistency by cataloging information so that it can be inserted wherever needed using your authoring software's copy and paste functions.

For extensive projects, you may want to develop worksheets to facilitate the cataloging effort. The cataloging effort can help you overcome the trepidation one feels at the outset of a large or complicated project. It gets you started developing manageable blocks of information and identifying the additional blocks that need to be developed.

Discussion

A context-sensitive help system is accessible from more than one entry point and provides multiple routes to other parts of the system. You, as the designer, have no way of knowing where your visitors will enter or how they will move through the system. Thus, you have limited control of the order in which a visitor acquires information. For any location in the system, you cannot make many assumptions about what the visitor has or has not already learned. To be safe, you can add amplifying information to clarify difficult topics or to clarify topics that seem (misleadingly) to be simple but where the user should be aware of unexpected difficulties.

This amplifying information also serves as a reminder to a visitor who may have encountered the subject elsewhere but does not recall important details. Often a few words or a single sentence is enough. Sometimes more details are appropriate. If you have already constructed a catalog of information, then you can save time as you develop the help system, because the amplifying information is already available for easy multiple insertions.

When setting up a help system, begin by cataloging descriptive information that you know needs to be presented. For software, this could include process overviews and descriptions of screens, tabs, subscreens, reports, core functions, buttons, fields, options, and so forth. Structure the information in top-down format so that you always begin with a brief summary statement. Add greater detail and subordinate facets in succeeding sentences and paragraphs in your catalog. Mark for special emphasis those points in the workflow that could cause frustration if the user has not performed the prerequisite functions or where user actions are potentially calamitous (such as deleting something that then deletes everything hierarchically below the deletion point).

Cataloged information can include more than one category of information for a given type of item. For example, information about a software screen could include information about the actions or circumstances that cause the screen to display, what the screen lets you do, what access restrictions might apply (lack of security permission, lack of appropriate data, and so on), descriptions of controls (buttons, options, and so on), and so forth. Catalog the information for each screen in the same order and with the same phraseology.

As you develop your system content, add the amplifying summary statements as needed (using copy and paste functions). You can insert further details by copying from your catalog. In practice, cataloged information gets plenty of use and reuse.

Example

In the following example, sentence numbers are strictly for reference. They are not part of the catalog. Similarly, bolding and italicizing of information is purely for illustrative purposes.



Full catalog data for the Transaction Summary Report screen purpose:
Use the Transaction Summary Report screen to generate, view, print immediately, or defer printing a transaction summary report. (#1)

You can enter a date range for the reporting period and sort the report by your choice of date, customer, or stock number. (#2)

You can perform the functions on this screen with Execute or higher access permission. (#3)

Selected reuses:
A step in a procedure could describe the use of a button that opens the Transaction Summary Report screen:

Click the Transaction Summary button to open the Transaction Summary Report screen. This screen lets you generate, view, print immediately, or defer printing a transaction summary report. (#4)

A description of the Transaction Summary button could be:

Transaction Summary button:

Opens the Transaction Summary Report screen, which lets you generate, view, print immediately, or defer printing a transaction summary report. (#5)



In this example, the screen name and the summary of its purpose from the catalog sentence #1 have been placed in selected reuse sentences #4 and #5. Catalog sentences #2 and #3 are potentially reusable as well. The full catalog information would be used "as is" when describing all the functions that are available on the Transaction Summary Report screen.

Worksheets

For large projects, I create worksheets that encourage me to develop information in a consistent fashion. The worksheets give me a compact view of all the items that need to be covered by my documentation, and the worksheets hold the information as it develops. Assembling information in this way is also a good technique for starting on a project that might otherwise be overwhelming in magnitude or complexity.

Originally, I created master worksheets for the application and its screens, tabs, and instructions. Using these masters, I then developed content-filled specific worksheets for the application and each screen, tab, and group of related instructions. In time, I found that the instruction worksheets were not especially useful. Once I have filled in the other worksheets, which are descriptive in nature, I can relatively easily write the instructions on the fly as I develop the help system. Therefore, I no longer bother with the instruction worksheets.

The following table simulates one of the many worksheets that I developed for a recent project. I entered fictitious information in italics to illustrate what I added to a screen data worksheet.

Screen Data

Name [code]: Stock Item Lookup screen [APM-1]
Parent applic: Acme Parts Management System
Purpose:
(fr Rqmnt Spec)
Use the Stock Item Lookup screen [APM-1] to search for and retrieve a stock item by number or name.

You can select to either modify or delete the selected item.

With Execute access permission you can perform the view-only functions available on this screen. You must have Update or higher access permission to select to modify item data and you must have Massacre access permission to select to delete the item.

Screen ahead:
  • Stock Item View screen [APM-2]
  • Stock Item Edit screen [APM-3]
  • Stock Item Delete screen [APM-4]
Screen back: N/A
Tab summary: Tab Description
By Number tab [APM-1A]

Lets you search for and select an item by stock number.

You can use the wildcard (%) in combination with 2 characters to help define your search.

With Execute access permission, you can perform all functions available to this tab.
By Number tab [APM-1A]

By Name tab [APM-1B]

Lets you search for and select an item by name.

You can use the wildcard (%) in combination with 2 characters to help define your search.

With Execute access permission you can perform all functions available to this tab.

By Name tab [APM-1B]

Notes: (if any) N/A
Buttons: Button Description
View Opens the Stock Item View screen [APM-3], which lets you view but not modify data for the selected item.
Edit

Opens the Stock Item Edit screen [APM-4], which lets you modify data for the selected item.

This button is inactive if you do not have Update or higher access permission.

Delete

Opens the Stock Item Delete screen [APM-5], which lets you delete the selected item from the database.

This button is inactive if you do not have Massacre access permission.

Return

Closes the Acme Parts Management application.

If changes have not been saved to the database, a dialog opens and gives you the opportunity to save the changes, ignore the changes, or cancel the impending action.

Options: Label Options
Select one

All: Makes all items from all vendors available for the lookup search. This is the default option.

By location: Displays a list of vendors from which you can select one or more. This limits the items available for the lookup search to items from the selected vendors.

Pop-up menu commands:
(rt mouse)
Command Description
N/A

The design of a worksheet naturally follows the design of the help system. In the example, the Tab summary appears to be unnecessary, because its component pieces will be repeated as appropriate in the tab worksheets. But for this project, it is useful to define the tab purposes in one place, because I have a Tab summary help topic for every set of tabs. Having the tab information in one place means that the Tab summary help topic is essentially ready to go. I have even included the linking text and underlined it as a reminder that it is to be linked when I build the help system.

Properly laid out and filled in, the worksheet helps identify and organize the material that needs to be covered by your documentation. It also makes building the final help system much easier.

Conclusion

Technical information needs to be presented with consistent terminology and phraseology, as you know. Consistent terminology helps avoid confusion with similar but different subjects. Consistent phraseology helps keep the presentation clean and simple. (Do not underestimate the value of "apparent simplicity" in reducing the intimidation factor that many people experience in working with technology. A clear and consistent user manual can lead directly to a user's perception that the subject matter is "not all that difficult" to grasp.)

Cataloging information helps ensure consistency. Cataloging information in top-down fashion adds flexibility to consistency. Building a catalog of information at the outset of a project helps ensure consistent terminology and phraseology, because you do not have to look far to see how you "said it last time" and because you can reuse it simply by copying and pasting. Later, if something needs to be changed, you can do it easily using your software's search and replace function, because you do not have to search for all conceivable variations to find the text to change.

If someday our help systems provide the ability to dynamically display single-source data, then information that is cataloged and structured for reuse will be ready to take advantage of that ability.


Alfred Barten is a Senior Member of the STC. He develops online help systems for General Dynamics Defense Systems in Pittsfield, MA. You can reach him at .

   
 

Resources