In 1995, I wrote a column for Hyperviews called How Long Is A Topic? Six years later, I still get the exact same question when running help development courses. Because of that, this column recaps the original discussion in order to help you define topic length standards.
We can sum up the issue of topic length in two questions:
Sadly, there are no pat answers. Instead, there are two alternatives single-window or multiple-window length. Your choice depends on your material and the projects design.
A single-window topic obviously fits into one help window. Users dont have to scroll or hunt for information in a succession of windows. It sounds ideal, and many companies initially specify it as the standard topic length. However, it has some major drawbacks.
Some Material Cant Be Covered In One Window
If a topic is too long to cover in one window, you have to artificially (and perhaps arbitrarily) break the material into separate topics. If the material has natural break points like subheads, its easy. Make each one a separate topic.
Consider the command reference chapter in a software users guide. Typically, each command description has Overview, Syntax, Options, and Examples sections, and may have others. You can make each complete command description one topic, or make each section a separate topic and tie them together with jump links. However, this approach itself has problems.
Turning sections into topics increases the coding work because you have to create multiple topics instead of one topic. Theres also a risk of inconsistency. If an entire command description fits in one window, you may be tempted to keep all its sections together in one topic and only break up command descriptions that are longer than one window. But this is inconsistent and may confuse readers. To be consistent, you have to break each section in each command description into a separate topic, even if that section is one word long. Finally, this approach assumes that the material has natural break points, like sections, in the first place. What if its just a lot of text?
You can create artificial break points at the cost of hurting your budget and schedule. Users may also get irritated at having to keep clicking on a browse button or Continue button. Like it or not, some material is just long, and if that material forms a natural chunk, breaking it up could reduce usability and clarity. And what happens when users want to print the material? Rather than just printing the one topic, users now have to print multiple topics. Its not a major problem, but little problems have a way of adding up.
Heres my favorite personal example
The longest topic I ever created filled 39 windows. It was the online version of a 17-page write-up of a type of mathematical analysis used for infrared spectrometry. The topic consisted of a series of partial differential equations, each followed by a definition of the equations variables and any additional related explanation. Why not break it into separate topics instead, one per equation, with Next and Previous buttons at the bottom of each topic?
The point of this example is to illustrate the need to think carefully about design and to be willing to break the rules when necessary. In my example, the topic violated every unwritten rule about topic length. But it worked. Some subjects just need long explanations. (Fortunately, situations like this are rare. In my experience, about 65% of all topics fit into one window, 33% require two to four windows, and less than 2% require five or more.)
Single-Window Topics Are a Formatting Nightmare
Lets assume that you managed to squeeze the topic into one window. Any format change, such as widening the margins to add white space, may be enough to push the material onto a second window. If this happens, you might be able to edit the material enough to get it back into one window but you'd be doing so for the wrong reason for the sake of design rather for its content.
Single-Window Topics Are Hard to Update
Again, assume you managed to squeeze the material into one window. Adding one word, maybe even one letter, may be enough to push the material onto a second window. Again, you may be able to edit the material enough to get it back into one window but youd be editing for the sake of design rather than content.
Single-Window Topics Are Hard to Translate Because of Word Inflation
Text inflation metrics vary. The one I learned was that translating from English to most Romance languages boosts the word count by about 33%; translating into German doubles it. (Next time you buy a product that comes with a multi-language instruction sheet, compare the instructions in different languages and check the relative word counts.) So if you squeezed every topic into one window through ferocious editing, you may see that effort wasted the first time the material gets translated.
By the Way, What Exactly Is a Window?
Ive been using a window as a unit of measure but what exactly is it? In the early WinHelp days, window referred to a full-screen window. This caused many usability problems and developers quickly switched to smaller windows. (Most of todays Web-based help systems are going back to full-screen windows.) Of course, what might have fit into a full-screen window might not fit into a fractional-screen window. Or you might force the material into a fractional-screen window only to have a user resize the window and completely ruin your effort.
Allowing topics to stretch over multiple windows avoids the problems described above but adds new ones.
Multiple-Window Topics Promote Wordiness
With multiple-window length topics, nothing forces you to write tightly. If a topic can stretch over two windows, why not three? This has nothing to do with online format; its simply an issue of writing discipline. But the lack of topic length restrictions does nothing to enforce that discipline.
Multiple-Window Topics Require Using Mid-Topic Jumps and Keywords
Jump links or index entries take users to the top of a topic. This doesnt help if users want some material nine windows down. Theyll have to scroll and read until they find the desired material, which detracts from usability. Mid-topic jumps and keywords are easy to create. However, using them may alter your linking strategy (to be covered in the next column) since it affects how often you link a particular term within one topic.
Given these pros and cons, can we answer the question how long is a topic? In my experience, single-window topics are more trouble than theyre worth and the simplest rule is as long as necessary and as short as possible. This is not as satisfying as a fixed number, but it is more realistic and a lot safer.
|Neil Perlin has 22 years experience in technical writing, with 16 in development, consulting, and training for various types of online documentation and tools including WinHelp, HTML Help, CE Help, RoboHelp, and some now known only in legend. Neil writes about online documentation, speaks to computer societies, the STC, and other groups, and is a senior member of the Boston chapter of the STC. He offers training, consulting, and development for various types of online documentation, XML, and the mobile wireless Web through Hyper/Word Services of Tewksbury, MA. You can reach him at firstname.lastname@example.org, www.hyperword.com.|
Practical Magic Reluctant Trainer Web Review Book Review
Resources & References Home
Fall 2001 (Volume 4, #4)
Copyright © 1998, 2002 Society for Technical Communication