Why Long Topics Are Better for the User
In my previous post, Do Short Topics Make Information More Findable, I argued that shorter topics make it more difficult for users to find information. I ended the post by saying that topics that are more substantial make content more findable.
But how big should the topics be? Obviously not the length of a book, because that switches us right back into the book paradigm.
There's probably not an exact way to determine topic length, because so much depends on the context of the information and the task at hand. But basically, a good topic answers a good question.
What's a good question? Questions can scale to a low or high order, being very specific and mundane to being abstract and conceptual. A one-sentence topic might provide the answer to a question (e.g., How many feet are in a yard?), while a 300-page dissertation might provide the answer to another question (e.g., What was Chaucer's influence on the Renaissance?).
In other words, you could construct the question so that it scales for any length of topic.
However, if you can construct an intriguing question (or at least a relevant question within the user's business scenario), that question merits enough information for a good-sized topic.
The following table lists some good questions versus lower-order questions in what might be a help file for an SDK.
|Good Questions||Lower-Order Question|
|How can I get started with the SDK?||What does SDK stand for?|
|What kind of information can I access through the SDK?||What is the user list property that the SDK returns?|
|How do I make calls with the SDK?||What arguments does the constructor accept?|
|What methods are available to use?||What information gets returned when there isn't data?|
|How do I troubleshoot errors with the SDK?||What does error msg 4555 mean?|
|What kinds of outputs can I use the SDK to generate?||Can I create a list of users via the SDK?|
|How do you include the SDK library?||Where should the library be included in the page's code?|
|What are some best practices to make the calls perform faster?||Can I use local storage to cache the library and increase performance?|
The lower-order questions all lead to a quick one paragraph response. On the other hand, the “good” questions will require more detail.
Granted, not every system merits longer topics. For example, if you have an encyclopedia of birds, each entry is probably a bird description in your TOC. But for most help topics I've written, I think a good sized topic is usually around 500 to 1,500 words, with exceptions.
Why 1,500? In an earlier post I wrote, Making Help Content Enjoyable to Read -- Impossible Question?, I noted that Clive Thompson of Wired magazine says the most popular blog articles are about 1,600 words in length (see “Clive Thompson on How Tweets and Texts Nurture In-Depth Analysis”). 1,600 words is about a seven-page double-spaced essay. Granted, that's probably not a help article, but it bucks the idea that each web page should be short little snippets of thought.
Length alone isn't much of an argument. So why do longer topics make content more findable? Here are several reasons.
Reason 1: Fewer Search Results to Sort Through
First, the obvious argument. If a user searches the help, there are fewer results to sort through if the topics are lengthier. For example, if you don't present the user with 37 hits for “widgets”, it's more likely that the user will open (perhaps among 5 choices) the right search result containing the answer.
Reason 2: Browsing Becomes More Practical
If users don't find anything via search, they can browse the table of contents (TOC). Longer topics mean fewer TOC entries to browse through. The TOC that was once impossible to parse through is now something that users can glance at and get some meaning from.
Reason 3: Interconnected Learning Helps Users Learn More
Now for the insightful, compelling reason why long topics are better. Information that is grouped together increases the inter-relatedness of information, helping users see the larger picture about a topic they're interested in.
For example, If you have 10 separate topics about widgets, the user may land on “adding widgets” and find a quick answer but not realize that he or she can also “fork widgets” or perhaps “decompile widgets."
By grouping related information about widgets together, you increase the chances that users will broaden their understanding of a concept and leave with more knowledge than they arrived.
In short, browsing through a long page of content helps users discover what they don't know.
Almost every grocery store uses the tactic of the long page. You arrive at a grocery store for milk, eggs, and bread. Almost always, the grocery store puts those items in the back of the store, forcing you to visually “sort through” all the other goods in the store. By the time you make it to the mlik section and then to the checkout counter, you've picked up a box of cookies, some lunchmeat, and some macaroni that was on sale.
Long topics create the add-on learning for your users. The user who just had a quick answer about hummingbird wingbeat speed suddenly learns that some hummingbirds weigh less than a penny, can live up to a decade, and are the only bird that can fly backwards. If all of that information had been separated out into discrete topics, the user would have probably walked away with the wingbeat speed answer only.
Try this experiment yourself. Click the following two images and check out the difference in content. The topic on the left, from Askville.com, is a short paragraph only, while the Wikipedia article on the right is quite a bit longer.
While the Askville page gives you a specific answer, the Wikipedia page gives you information that you didn't even know to ask. Which approach to you prefer?
In summary, even if long topics don't deliver information faster to the user, they're a better practice because they help the user learn more through a tighter grouping of information.
Long Topics Are More Maintainable
I have a few other points to make about advantages with long topics -- they are much more maintainable. If you have thousands of discrete topics in your system, not tightly connected together, maintaining the information as a coherent whole when you need to make updates becomes a nightmare.
For example, let's say you have 20 topics about hummingbirds. Your subject matter experts push out new findings that change some aspects of our hummingbird knowledge. Now you have to hunt and peck around your help system for all the various topics that touch on hummingbirds. If the information were grouped together, you can more easily see the places you have to update.
Ways to Break Up Long Topics
So that my advice isn't misconstrued, I'm not suggesting that every technical writer suddenly start creating long walls of text.
A page of long text needs to be broken up by subheadings, graphics, lists, and white space. A great reference for designing the visual aspects of a page (not necessarily adding graphics, but influencing the visual nonetheless) is Visual Composing: Document Design for Print and Digital Media. See also my post titled Subheadings: Perhaps the Most Useful Technique in Technical Writing.
When a Topic Is Too Long
Although I like longer topics, there's a practical limit to a topic's length. When I've gone over 2,000 words with my blog posts, I've noticed that the comment count plummets. The web form doesn't work well with really long content. That's why I actually broke this post and its predecessor into two parts.
While blogging and tech comm are separate genres, the predominance of blogs on the web has set a trend for expected article length and attention span online. A good editorial is usually about 800 words for a reason. Just as a Windows PC has trouble moving around information more than 2GB, our brains also have trouble working in 2GB topics. Shorter is cognitively easier to handle. But not too short.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.