Best Practice: Topic Types

Helps often deal with a plethora of different information. Not only is the information required by different readers in different contexts, it is also collected from a range of sources of varying quality and style.

From our conversations with developers we glean those handy shortcuts and tricks that they spend extra hours programming. They provide lists of hotkeys and data types for us to compile. They provide lists of form names and database tables.

We consult the scope documents and find a raft of sales reasoning for implementing the software. They tell us about the numerous users clamouring for this new feature. We read explanations of business processes, and the key words that the market uses for this functionality.

We consult the product manager and note key executive points essential for the user to understand the function. They wax lyrical of the ways this will save the user time, and therefore general more sales.

The stack of information for our project stacks pretty high. But in there are the gems that trun a good help into a great one. The key to unlocking this is in the way we organise the information. With so much to go on the tendancy is to start pumping it into our help authoring tool, but this can result in a variety of topics covering the software from several angles, each one overlapping the next to a greater or lesser extend.

We need to get organised. And for me the key tool in this has not been a new super help technology or authoring tool, it has been some premeditated strategising. I needed to be able to categorise the information I had so that I could start to know what went where, and avoid repitition. One way this can be achieved is by defining a strict set of topics.

Definition: Your topic types need to be strict enough so that you know what information should be included, but also flexible enough to cope with the inevitable oddity bits of information. You should define a rough template for each type of topic that outlines the sturcture and content that will usually be included.

Relationship: There should be a clear progression from one topic to another. It can help to build up a model of how a user my read and cross reference each of your topic types. Ensure that you don’t have topics that are essentially stranded with low visibility.

Appearance: Once you have your ideal topic type set, you need to do some work to ensure that the user can tell what type of topic they are reading. It can be useful to get a graphic designer involved at this stage if possible. You should be providing visual clues such as colour, iconography and structure that signal to the user what sort of information they can expect to find.

If you are able to do this effectively, this means that you not only are able to produce streamlined helps that are easier to navigate, read and maintain, but you are also ready to move to new formats (such as DITA or MAML) that expect this sort of information definition.

You can extend your handling of information, by considering how you title your topics. A comprehensive and consistent approach to topic titles, essentially pick-up on ideas similar to that of tagging made popular by the recent success of del.ici.ous.