Practical Magic:
Specifying Standards For Topic Length

Everything old is new again …

By NEIL PERLIN
Boston Chapter

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:

1. Can we define (and adhere to) a maximum length?
2. Is there an ideal length?

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 project’s design.

Single-Window
Length Topics

A single-window topic obviously fits into one help window. Users don’t 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 Can’t 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, it’s easy. Make each one a separate topic.

Consider the command reference chapter in a software user’s 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. There’s 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 it’s 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. It’s not a major problem, but little problems have a way of adding up.

Here’s 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 equation’s 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?

• Some of the equation write-ups fit neatly in one window but others didn’t, so I would have had to arbitrarily break the latter topics into smaller chunks. However, to be consistent, I would have had to break all the topics into smaller chunks, requiring a lot more work.
  
  
• Putting the material into separate topics with “Next” and “Previous” buttons worked if the users wanted to go from equation to equation in sequence. But what if users wanted to go from equation 1 directly to equation 27? They would have to click “Next” 27 times as opposed to simply dragging the elevator box down the scroll bar.
  
  
• Printing could have been a problem. Users who wanted to print one equation would have been fine, but users who wanted to print the entire series of equations would have to print each topic individually.

• People ask why I didn’t keep all the equations in a single topic but create mid-topic jumps to each equation? There were two reasons: First, mid-topic jumps weren’t an option at the time (the early 90s). Second, even if mid-topic jumps were an option, how would the users navigate to the desired equation and how would they know which equation jump to even select?

• Mid-topic jumps are common in glossary topics, which put a virtual keyboard at the top of the topic. Clicking on a letter in that “keyboard” jumps you to that section of the glossary. Mid-topic jumps are also used in error message topics, where message numbers (0-10, 11-20, etc.) appear at the top of the topic. Clicking on one of those numbers jumps you to that section of the error message list in the topic. Why not do something like this with the equations?

• The problem is how to list the equations at the top of the topic to create the equivalent of the virtual keyboard. Listing them as 1, 2, 3… gives no clue which equation is which. The alternative is to list them by equation function, but the list would likely be too long to be of real use.

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

Let’s 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 you’d 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?”

I’ve 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 today’s 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.

Multiple-Window
Length Topics

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; it’s 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 doesn’t help if users want some material nine windows down. They’ll 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 they’re 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.