You can’t size topics for specific information needs

By | 2015/02/02
This entry is part 4 of 4 in the series Topic Patterns

One of the biggest traps in topic-based writing it the attempt to size topics so that each one meets exactly one user information need. It is tempting to suppose that this is the point of topic-based authoring. If the book is the wrong size because people only use them to look up bits of information, rather than reading them through, isn’t the point of writing topics to make the topic contain just the information the reader needs in the moment (so that they will read it through)? Thus we envision our reader’s needs mapping to our topic sets like this:


While that is a tempting vision, it leads to an impossible quest: trying to figure out how large topics should be to fulfill this requirement. Thus the biggest question in topic-based authoring is: how long should a topic be? It is the Goldilocks problem:


But as long as we think of topic size in terms of fully meeting individual information needs, we will never answer this question satisfactorily. after all, the bear’s possessions that Goldilocks used were each sized correctly for a different bear.

Different readers want different amounts of information, and even a single reader wants different amounts of information at different times. Not only can you not perfectly size a topic for all readers, you can’t even do it consistently for one reader. No matter what you do, some readers will want only bits of some topics, and some readers will want several whole topics.


When you need information to complete a task, locating the specific set of information that you need to get you unstuck always involves some degree of difficulty. Sometimes you will find all of it within part of a large information product. Sometimes you will find it across several information products from different sources. You can’t usually tell in advance which combination of these it will take, or even how much information you are going to need to reach your current goal. Reading is a voyage of discovery, and often what you discover is that you need more information than you thought. Each piece of information you find may refine your search or lead you in new directions.


This means that the process of finding information is iterative. Yesterday I was looking up how to create a temporary file name in Python. It did not occur to me when I began this search that there are security implications to this question, or that certain techniques for creating temp files work differently on different platforms, or that there are different techniques based on whether you want the temp file to stick around beyond the process that creates it.

What I realized at this point is that I had asked the wrong question. I wanted a temporary file name, but I did not actually want a temp file in the sense Python implements that feature. I just wanted a unique name to give to a file I was creating normally. And thanks to people on StackOverflow who had asked the same wrong question in the past, I discovered that what I was really asking for was a function to generate a unique string, which was then easy to find.

Most of my reading, in this case, was not solving my problem. But it was helping me get from my somewhat incorrect translation of a business problem into a technical question to the correct technical question. What I needed as a solution was a single line of code — far less than the size of a topic. But I needed a lot of other content to get me there.


This wayfinding from slightly wrong question to correct answer is a huge part of what technical and marketing communication is really about. And every reader’s wayfinding path is different. Every reader’s path through content is formed by a unique combination of what they don’t know, what they are trying to do, and what they didn’t understand the first time they read it.

This path is not formed by reading a sequence of topics as a whole, and then selecting either a next link or an item from a series of related links. Readers hop into topics from search, glance around, sniff for an information scent, and move on as soon as they thing they have a fresh clue.

Their progress does not look like this:


It looks like this:


And the reason it looks like this is not because you got the topic size wrong, but that Papa bear looks at the world a lot differently than Goldilocks.

In fact, the reader’s true path probably looks even more complicated than that, full of false starts and abandoned paths. And this is where topic design can really make a difference. Not in creating a single perfectly sized topic that will meet all needs, but in making the reader’s wayfinding through the information set less chaotic and more straightforward.

This leads us to a somewhat counterintuitive proposition: the primary design consideration for topics is not reading, it is navigation.

The one topic/one need model (if it could be achieved) would give us an easy dichotomy between navigation and reading: Navigation would be something that happens outside the topic, and is the sole concern of information architects. Reading would be something that happens entirely inside the topic and would be the sole concern of writers.

But as we have seen, the perfectly sized topic does not exist and reading and navigation are not separate activities or separate concerns, they are inextricably integrated parts of information wayfinding. Readers do not navigate and then read. They read and navigate at the same time.

Indeed, when people use content in a bottom up fashion (whether or not it was designed that way) they spend little time on purely navigational elements. They move through content sets using search and social media, and by following clues (and hopefully links) in the pages they find in those clusters. This means that the content itself, whether read directly or abstracted in search results, is the primary place navigation happens.

Happily, this leads us to a much more satisfactory answer to the question of how large a topic should be. The keys to determining it size are not individual information needs, but shared navigational needs. A topic should be big enough — and the right shape — to be an effective navigational unit.

One of the keys to being an effective navigational unit is to have a strong and clear information scent. This means that, within the information set, the topic should be clearly distinct. If you have topics that are too small, many of them are going to seems similar to each other and it will be difficult to pick the correct one out of a batch.

If topics are too large, on the other hand, it is not going to be clear what they are about because they will end up being a about several things. Either their information scent will be dominated by the first thing they talk about, obscuring the rest of the information, or it will be a horrid mix of many scents, obscuring them all.

In either case, search results become difficult to use, because neither the too-large topic nor the too-small topic is easy to identify in a set of search results. (Nor is it easy for the search engine to determine what the topic is about.)

But correct sizing of topics is not the only factor to consider. Because navigation continues within and between topics, the internal structure of topics should be designed primarily for navigation. This means giving the topic a clear, distinct, explicit, and consistent structure.

Some writers are uncomfortable with this level of structure. Sometimes this is because the structure is imposed on them from outside and does not fit the material well. But in many cases the writer feels that the structure inhibits the natural flow of their prose, and that they, as a writer, are better able to craft a highly readable topic without the constraints of the structure.

If the readability of the topic as a whole were the primary design consideration, they might have a point. But as we have seen, navigability of the topic set should actually be the prime driver of topic design. (And note that it is navigability of the topic set, not just the individual topic that drives this, since readers frequently traverse several topics on their journey.)

Both these factors (poorly fitting structure, and the writers desire to craft an ideal reading experience at the expense of navigation) indicate the need for writers to be deeply involved in the process of designing topic types — with a full understanding that navigation is at least equal in importance to readability.

Dividing the tasks of navigation and readability between information architects and writers respectively is not going to produce an information set in which each reader can quickly and easily find the unique set of information they need at any one moment. Readers find their way by reading and navigating at the same time, and we need to create topics that are optimized for the inseparable twin tasks of reading and navigation.

This is why topic patterns are an important part of topic-based writing. Topic patterns enhance the navigability of topics and topic sets. Also, mature and well-thought-out topic patterns can effectively balance the demands of navigation and readability, producing a topic that works as well for the reader who passes through it as for the reader that reads it from top to bottom.

You cannot size topics perfectly to meet individual information needs. You can size and structure them for optimal navigation across the information set. That is how you create an information set that both Goldilocks and each of the three bears can use successfully.


Series Navigation<< FAQs are Still Useful

9 thoughts on “You can’t size topics for specific information needs

  1. Jonatan Lundin

    This makes a lot of sense. It is impossible to craft the “perfect fit” for everyone.

    Instead, I argue that technical communicators should provide short answers in user assistance, IF

    • the user assistance environment is capable of providing a rich context, (is capable of clearly indicating which question an answer is answering), and

    • it gives the user the opportunity to easily find answers to follow or related questions (

    In a laboratory experiment I did some year ago, I found that users do not read an entire topic (page). Very often, they read the first sentences and then jump elsewhere (much as you describe in this post). See more here:

    Linking topics becomes the challenge and focus for information architects. There are of course many ways to establish relations. One is to use and established topic classification (

    1. Mark Baker Post author

      Thanks for the comment, Jonatan. Those parameters seem to me to pretty much describe the constraints of reference material. Reference material provided swift access to brief answers for those who know enough to look it up. I have always believed that tech comm tends to neglect reference material, and that a good reference is the necessary bedrock on which everything else is built.

      Linking is indeed the key issue. There are two key things you need for a successful linking strategy. You need to clearly identify what topics are about, which you can do with a topic classification system, either external or internal, or by a process of semantic identification based on elements of the content.

      The second key it to identify what a topic is talking about, which is different from what it is about. An omelet recipe is about cooking omelets. It talks about eggs and pans and cheese.

      While many systems provide way of capturing what content is about, few if any capture what it talks about, which leaves link management in human hands, making it expensive and prone to failure. Thus we tend to do a poor job of helping people find their way through or content sets.

      The SPFE project is designed to remedy this deficiency and allow us to link effectively.

  2. Nolwenn

    The short description in DITA provides a way to give the users information to help them decide whether or not they should continue reading or skim through that topic.

    1. Mark Baker Post author

      Thanks for the comment, Nolwenn,

      Indeed, establishing context is vital in topic based writing, and DITA’s short description provides a generic container to do that. I’ve encountered some problems with short descriptions, however:

      • It is just a generic container, so it does not model how context is supposed to be established in a particular topic type.

      • It is not really clear how the short description should appear. Should it be treated as a kind of executive summary visually set apart, or should it appear as the lead of the regular content. In other words, should it summarize or introduce the topic? I see writers using it in several different and inconsistent ways.

      • What happens to the short descriptions when you chunk several building block topics (sized for effective reuse) together to form one presentation topic (sized for effective navigation and readability). Do the short descriptions of the building block topics get suppressed, combined, or presented separately in the body of the presentation topic? Does the presentation topic get a short description of its own, and if so, where does it come from?

  3. Vinish Garg

    You make a lot of valid points on topic length. I want to add another factor that colors the documentation team’s decision making process.

    While planning articles for a KB, I felt that a few topics could grow too long and wondered if I could revisit the IA. When I discussed it with the board, I learnt that they would rather prefer long topics because the current trend in blogs and thought leadership articles was towards longer articles. They added that it was a B2B product and the audience is in the habit of reading long posts and articles, and so long topics in documentation too should be acceptable.

    Do you see any merit if such ‘trends’ influence our thinking while planning trends? What if the trend changes to short posts in 2017? Will the same board advise me to restructure the topics accordingly? 🙂

    1. Mark Baker Post author

      Thanks for the comment, Vinish.

      I think you have to be very careful about how you read the data when discerning trends of this type. For instance, suppose you introduce a complex feature into your product. Complex features require more explanation, so you produce some longer topics. The feature is new, so a lot of people read about it. This will have the effect that the typical length of topic that your audience is reading will increase over the period following the introduction of the topic.

      In the gross stats, this is a trend toward people preferring longer topics, but it does not really have anything to do with people preferring longer topics. It is all about a lot of people reading about a complex subject at the moment.

      Certainly, in the world at large, we are seeing a reversion from the trend toward writing arbitrarily shorter topics, which resulted in the first place from a crude misreading of the data by rolling up stats from many different kinds of content.

      Here is what I think about topic length: people like to do easy things more than hard things. Easy things can be described in fewer words than hard things. Therefore more people will read short content than long content because the short content is associated with the easy things that they prefer to do.

      But people also do hard things when they have to, and if you make the content describing hard things shorter than it needs to be to describe them adequately, you will make doing those hard things harder still.

      I think once people started to realize that short content about hard things was not being read or shared, they started to write longer content about them and found that this improved things.

      And then some people drew the conclusion that it was better to make content longer, quite apart from how long it needed to be to describe what it was supposed to describe. Which, of course, is nuts.

      Length, in itself, is not a meaningful criteria. The right size for content is as long as it needs to be to cover what it covers. It is best, therefore, to drop length per-se from the information design task altogether.

      A topic is the right size if:

      • It is self-contained, without linear dependencies
      • It has a specific and limited purpose
      • It establishes its own context clearly
      • It follows a well-defined topic pattern
      • It assumes the reader is qualified (by a reasonable definition of qualified)
      • It stays on one level

      And it is well integrated into the larger content set, enabling effective wayfinding, if:

      • It links richly to related topics along lines of subject affinity
  4. Nancy Faerber

    I agree with your premise about information foraging and the need for robust inter-topic navigation. Which leads me to thinking about testing/evaluating the effectiveness of the navigation. Your diagrams showing a highly individualized way of traversing through topics reminds me of personas. I’ve used personas to guide me in writing help content it terms of user goals & tasks, tone, word choice, etc, but must admit that too often the personas fall by the wayside during the documentation review process (which in crunch times tends to focus more on accuracy, completeness, formatting, resolving broken links, etc.) Given how highly individualistic each reader’s path in (and out) of the help documentation can be, returning to the personas during the review process could also be a way to evaluate the paths provided through the content.

    1. Mark Baker Post author

      Thanks for the comment, Nancy.

      One of the interesting questions about the use of personas in design is whether/when you look at the intersection of the personas (what they all have in common) and the union of them (all the characteristics found in any one of them).

      The point of intersection for documentation is the task. That is, all readers, no matter how much they differ in other ways, are all attempting the same task. The design of individual topics tends to focus on the intersection of personas. This is what the EPPO principle that a topic should assume the reader is qualified it really saying: focus on the task and on the person who normally does the task. This is necessary, since without this principle topics become bloated with material most readers don’t need, which make them harder to use for everyone.

      But navigation is about the union of personas: all the ways in which individual users differ from each other. Every reader takes a different path through the content because of all the ways in which they are different from each other. And this does apply only to the outliers. Every reader has these distinct features that they do not share with others, and therefore every reader needs to navigate.

      So I think you make an excellent point. When it gets to crunch time we can easily start for focus only on the intersection of personas, not the union. But the problem with that is that the intersection of personas does not represent the whole of even a single individual person. So if we neglect the navigation, we neglect the needs of everyone.

      1. Nancy Faerber

        Thanks, Mark, for the further explanation. The intersection/union analogy paints a good visual. I’m in the process of re-designing & modernizing a tri-pane help system, while at the same time, pulling my own mindset forward and away from the book paradigm. Your book and these subsequent posts have been very useful.


Leave a Reply to Jonatan Lundin Cancel reply