I'd Rather Be Writing » table of contents

Topic-Based, Hierarchical Navigation [Organizing Content 5]

Tom Johnson — Wed, 19 May 2010 14:28:29 +0000

I mentioned that topic-based, hierarchical navigation, which is the standard for 95% of the help files I see, is becoming a tired, less-than-useful navigation system. We rely on this system too much as technical writers, and it’s not that helpful to users. Here are a few examples to demonstrate this.

I read an intriguing article today called 5 High Paying, Low Stress Jobs on Yahoo Finance. It lists technical writing as the fifth least stressful, high-paying job. I wanted to share the article, so I added it to the Technical Communication Library (TC.Eserver.org).

Without using search, go to Eserver TC Library and browse to the article using the topic-based navigation system. Can you find it?

Now move on to a more difficult challenge. Go to the Yahoo Directory and browse to the Yahoo Finance section (where the article was published). Can you find the site and article?

Let’s try more examples. Suppose you’re learning WordPress, and you want to know what a “widget” is. Using the topic-based navigation (not the search) on the WordPress Codex, can you find the topic that explains widgets?

Now go to the online help in Flare 6 and, using the topic-based navigation, find where it explains how to create image maps.

Let’s say you want to add a caption to a youtube video. Browse the topic-based navigation in Youtube’s help and try to navigate to the topic that explains captions. Bonus points if you find how to create captions in other languages. (Again, don’t use search — we’re evaluating the usefulness of topic-based navigation systems.)

Now go to Chrome’s help and navigate to the topic that explains how to maximize or minimize text and images within the browser.

If you have Snagit, open their help and try to navigate to the topic that explains how to hide your mouse before taking a screen capture.

Try navigating through Audacity’s help on the Floss Manuals site and find how to export your audio file as an MP3 file.

Go to Hulu.com and browse their TV topics navigation to find the TV show Kings. Can you find it (again, without using search or the other, non-topic-based navigation features)?

In any of these examples, did you enjoy trying to guess the technical writer’s logic of organization as you navigated the folders? Sure the logic usually makes sense to the technical writer, because he or she wrestled with the topics and grouped them, probably at great pains, into folders that seemed to make sense.

And perhaps the folders even make sense on a content level as well, that is, the organization is centered on the actual characteristics of the content, not some invention in the writer’s mind.

But even so, most likely this natural order isn’t readily apparent to the new user, who is coming to the material for the first time, without any background or grounding in the same concepts and assumptions and perspectives as the one who organized the content.

As a final blow to topic-based navigation, go to STC.org and find either the bylaws for the association or the latest minutes from the board. Could you find them? Several people told me they’re readily available on the site. But which bucket do you look under? Publications? Membership? Education? Couldn’t the bylaws or minutes fall under any of these containers? It depends what you think the bylaws and minutes contain. It depends how you interpret their purpose and function.

Just because topic-based navigation is often frustrating, as I hope I demonstrated in the examples above, it doesn’t mean we should abandon this system of organization entirely. From a help-authoring perspective, you usually have to group your topics into some containers simply to work with the topics.

But whatever containers we ultimately choose, in the end, if these containers do not exactly match the organizing logic in the user’s mind, the user will take one glance at the help, maybe expand a few folders to peer inside, and then give up. This is why topic-based navigation shouldn’t be the main system of navigation for help content.

Blog Sponsors

Imposing Order Versus Observing Order [Organizing Content 4]

Tom Johnson — Tue, 18 May 2010 14:19:53 +0000

It’s easy to postpone organization. We begin writing discrete help topics, hundreds of them, and then try to group them together in a logical way. But here’s where the problem starts. What does it mean for a system of organization to be “logical”? And how does the user navigate this logic we create?

Our system of organization partly determines the findability of the content. Without findability, we might as well not even write help at all. It’s exactly this lack of organization/findability that turns so many users off with help content. When you click the help button and see an immense amount of folders and subfolders and sub-subfolders, all organized in seemingly impenetrable ways, it overwhelms users. They give up within seconds of their foray into the help.

As help authors, it’s so easy to be seduced by technical distractions and overlook the content. We get drawn into styles and design, the look and feel of the help content, the single source rendering between print and online, the parallelism of titles, and the exacting conformity to our style guide. These technical bells and whistles distract us from more fundamental matters of content organization.

But content organization is fascinating. The way a help author lays out the help topics in a table of contents shows you more than simply a list of topics. It shows you how the author has wrapped his or her mind around the content, how he or she has chosen to shape order from chaos. It shows you how the author understands the user. And it shows you one perspective on the structure of the content.

Organizing the Periodic Table of Elements

Organizing a jumble of help topics into a natural, beautiful order that strikes clarity in the mind of the user is no different from the scientific urge to classify, to organize, label, and categorize. Nothing illustrates this better than the story of how Dmitri Mendeleev organized the Periodic Table of Elements.

Dmitri Mendeleev

Before Dmitri Mendeleev organized the table, he traveled extensively in Russia on trains flipping around a stack of cards that had the elements and their behaviors written on them. Sorting and resorting the cards, he kept searching over and over in his mind for a pattern, for a principle he could observe that would lend itself as the organizing pattern for the elements.

Sure, the elements had different atomic masses. The atoms of some elements were heavy; others were light. But the atoms also displayed other behaviors. Some elements were friendly with other elements; other elements were shy, like loners.

This seemingly random array of heavy, light, shy, friendly characteristics made it tricky to organize the content in a logical way. What was the right way to organize these 90+ elements? What underlying logic explained the element’s natural classification and hierarchy?

The right system of organization finally came to Mendeleev in a dream. A sudden flash of insight, not an order he created, but an order inherent in the content he observed. He finally saw the elemental grid.

He not only arranged the elements by the degree of atomic heaviness, but also found that the elements had other patterns that repeated periodically. Hence Mendeleev called his table a periodic table, because the patterns repeated with specific periodicity. Through the repetition of this pattern, Mendeleev also predicted the existence of elements not yet discovered.

Radiolab

I listened to this story of Mendeleev organizing the elements on Radiolab, with hosts Jad Abumrad and Robert Krulwich. They ended the story with the following question: Was this organization an invention that Mendeleev imposed on this otherwise random set of elements? Or did Mendeleev see the underlying law that naturally organized the elements? In other words, is organization a human fabrication we impose on content, or do we observe an organization that is naturally inherent in the content?

By the way, I excerpted a short, one-minute clip from the Radiolab podcast here. Listen to the way Oliver Sacks, Abumrad, and Krulwich tell the story of Mendeleev:

Mendeleev apparently rode these trains for years before finally reaching his organizing vision. Here Abumrad and Krulwich elaborate on the principle that Mendeleev rationalized:

And the final result today:

Periodic Table

The Problem with Scientific Classification

After listening to the story of Mendeleev organizing the elements, I was convinced I too could find, if I just looked carefully enough, an underling pattern that would serve as the perfect organization for my 200 help topics with Project Swordfish.

But the more I looked, and the harder I thought, I could not come to any conclusion except that a software application is man-made. It does not conform to any unseen natural laws in universe, and finding a natural pattern is an unachievable illusion.

The only system of organization that approximates a natural law is to organize help according to the psychology of the user. In other words, rather than looking at an underling organizational structure in the content, look at the way the user’s mind organizes and structures the content instead, and use that mental principle as the pattern.

Having thought through all of that, somewhat fruitlessly, I scrapped the other content organizations and created a standard topic-based TOC that looked somewhat like the following:

Exchanges
     Organizing Exchange Locations
     Evaluating Suitable Environments
     Reading Informant Microgestures

Burn Notices
     About Burn Notices
     Managing Your Life After the Burn Notice
     Dealing with Fake Burn Notices for Double Agents

Sting Operations
     Finding and Using Citizen Operatives
     Recycling Burned Agents for New Operations
     Evaluating Environments in High Risk Situations
     Deciphering Informant Trust
     Calculating Risks Based on Informant Credibility and Environment Security

This approach to the TOC follows the conventional topic-based approach, attempting to group like-minded content into its logical topic container.

Limits of Logic

This standard seems like a good approach, except that topics don’t always fit neatly into their “logical” containers. You can see that in the last section, Sting Operations, the tasks include evaluation of informants and assessment of environments — similar to topics under Exchanges. The remaining help topics also contained similar overlap.

The lack of a clean, neat grouping of content into topic containers is not just an exception, like the egg-laying platypus is an exception to its mammalian classification. Content in real projects is messy. It overlaps. It duplicates. It stretches outside of its row like an overgrown tangle of weeds. It could easily be classified in several different containers. When you look at the logic of the organization, it often tells you more about the organizer than the actual content. In the end, it isn’t really logical at all.

According to Abe Crystal in the Tech Comm Journal, “the idea of a single, unified hierarchy,” in other words, the standard topic-based containers organized in a hierarchical, logical arrangement, is “the fundamental weakness of standard IA [information architecture] frameworks.”

Yes, this single, unified hierarchy, the traditional topic-based approach to classifying content, which I struggled to grasp and implement with my 200 topics, is an old, tired framework. Instead, Crystal suggests moving in a more fruitful direction: faceted classification.

—————-

Crystal, Abe. “Facets Are Fundamental: Rethinking Information Architecture Frameworks.” Technical Communication Journal, Vol 54, No 1, Feb 2007

Blog Sponsors

Things Fall Apart, The Centre Cannot Hold [Organizing Content 3]

Tom Johnson — Mon, 17 May 2010 14:27:33 +0000

Let’s fast forward a year. Assume you have explored Swordfish and have hammered out a lot of help topics — nearly 200 help topics, in fact. You have met with subject matter experts and extracted critical information from them for many months. You have explored Swordfish inside and out, documenting every possible task and setting, and now you have a ton of content.

The help topics you created seem endless. You have checked their accuracy against the constantly updated Swordfish interface, and you have made a seamless flow from online help to PDF format. But now, at this moment, near the end of the project, you face the problem of content organization. You have so much content, it seems all one giant jumble of information. It needs to be organized better, with a sounder logic and structure, but how?

Attempting organization

In setting up my 200 help topics, I initially grouped the topics into various folders — for example, Covert Operations, Stings, Exchanges, Drop-offs. And then I titled the subfolders in each folder as “Basic Tasks” and “Advanced Tasks” to follow the model of increasing agent permissions. So the folder organization looked like this:

Covert Operations
     Basic Tasks
     Advanced Tasks

Stings
     Basic Tasks
     Advanced Tasks

Exchanges
     Basic Tasks
     Advanced Tasks

Drop-offs
     Basic Tasks
     Advanced Tasks

It soon was clear that no one understood what constituted a basic and advanced task, so I changed these subfolders to a grouping of content by role: “Super Agent Tasks” and “Regular Agent Tasks.” I structured everything in the help this way, assuming that this model would fit the majority of agents perusing the help. They could then navigate to the subfolders based on their known and probable role.

Covert Operations
     Regular Agent Tasks
     Super Agent Tasks

Stings
     Regular Agent Tasks
     Super Agent Tasks

Exchanges
     Regular Agent Tasks
     Super Agent Tasks

Drop-offs
     Regular Agent Tasks
     Super Agent Tasks

Feedback from both colleagues and users resisted these roles. “The folders are too general,” one colleague said. “I have no idea what Regular Agent and Super Agent Tasks mean. You need something more descriptive.” A user echoed the same thing, asserting that the folders were too general and vague.

Technical distractions

Release dates drew near. Although the folder naming conventions weren’t ideal, I was proud of the single sourcing model I had set up. The online help single sourced to a PDF printout without any modification of the PDF at all. In fact, I even set up a recurring job to automatically republish both the online help and PDF every day at 2 p.m. It was a completely hands-off, automated process.

But then something happened. A few days ago, one of the chief agents in the department mentioned he was preparing a presentation to a set of field agents, and could I show him where to print the quick reference guides and user manuals?

Gladly I showed him the links, but because I had a few days until the deadline, I decided first to read through the PDF, which previously I had hardly glanced at except to ensure proper formatting and PDF rendering.

Printing out the PDF, which essentially duplicated the online help but in print format, was 197 pages. I didn’t realize it was so long, but I pulled out my red pen and started to proceed through the topics with patience and anticipation.

Non-linearity and linearity

As I moved from topic to topic, I noticed that the topics didn’t flow well together. Some topics repeated information stated on other topics. Other topics introduced concepts in some places but didn’t include tasks related to those concepts until pages later, as they were interrupted by other topics.

Overall the content was too detailed, too wordy, and too long. I drew big red slashes on numerous pages and wrote “Cut” more times than I could count. I wanted a shorter reading experience. After page 50, I had read all I wanted to.

The chief agent’s assistant also agreed that she could not print 197 pages for each participant. The length seemed ridiculous. Was the application really that complicated?

Somewhere, something had gone wrong. I entered into the project with a couple of assumptions. First, I assumed help should be a mile wide and thirty seconds deep, that is, covering a wide array of topics in a brief way. Consequently, I had written dozens and dozens of topics that covered all kinds of scenarios. This might have been all right had I left the miles of topics in the online help, but I had also included these topics in the PDF.

Reading through the PDF, there was no flow, no tight coherence of ideas, no transitions from one idea and topic to the next. It was if someone gathered 200 Post-it notes written independently of each other and positioned them sequentially — and then was surprised when the content lacked flow from one Post-it note to the next.

I had another faulty assumption, one that I knew but had forgotten. Online help is a non-linear reading experience. A printed document is a linear reading experience. The two reading modes aren’t interchangeable. Reading through the PDF made that clear.

Crumbling organization

I noticed another problem in reading the PDF. The chapter titles Super Agent Tasks and Agent Tasks began to annoy me, even more now than before. What did they really mean? Nothing. As my colleague had pointed out, the titles only meant something if you knew what sort of tasks each role could perform (which I did).

But if you didn’t already know the limits of each role, grouping topics by role wasn’t helpful. You would only know to look in that role’s folder if you knew that role could perform that task. But most users wouldn’t know the tasks each role could perform. Many of them wouldn’t even know what roles the application had. So the folder names were somewhat meaningless.

The help file was falling apart on two levels now: poor folder/chapter titles, which left the organization of tasks vague. And also a hodgepodge of clashing topics in the PDF output, which didn’t result in a linear reading experience.

Blog Sponsors

Introducing Project Swordfish [Organizing Content 2]

Tom Johnson — Mon, 17 May 2010 13:56:07 +0000

Welcome to the new project you’ll be documenting: Project Swordfish. Project Swordfish is an application used by the FBI to train agents in virtual simulations of undercover operations.

With Swordfish, users can be super agents and regular agents. The super agents can configure the permissions of the regular agents with 20 different permission settings. This means the relevant help topics for any agent can vary from about 10 topics to all 200 topics, depending on the permissions an agent has.

An agent with all 20 permissions will find that every topic in the help is relevant. An agent with no permissions will find that just a handful of topics in the help are relevant.

Some of the permission settings for the agents include the following:

Allow agent to view master operations list
Allow agent to create new operations
Allow agent to close operations
Allow agent to create operation maps
Allow agent to add or remove members from his team

You get the idea. (By the way, this isn’t real.)

In Swordfish, agents are grouped into teams. The same agent can be on multiple teams, with different permissions on each team. For example, an agent can be a super agent on the Black Operations team, but a regular agent on the Public Operations team. Agents can even be double agents, so that they appear to be regular agents on a team but are actually super agents, and vice versa.

Project Swordfish has a moderately complicated interface that warrants approximately 200 help topics. Help topics include several types of topics: conceptual topics, task topics, videos, context-sensitive help topics, and FAQ topics. You need to create both an online help file as well as several printed guides. Your main task is to organize the help topics in a way that makes sense to users.

Content organization is the focus of this series, so that’s what the upcoming posts will explore — different ways to organize content from this hypothetical documentation scenario.

Blog Sponsors

Leaning Towards Longer Topics and Shorter TOCs

Tom Johnson — Tue, 23 Sep 2008 04:36:09 +0000

Everyone knows it’s a good practice to chunk your help material into discrete topics, but how granular should you chunk it?

Take a look at this Microsoft Word 2007 help topic on inserting headers and footers.

Example of a Quick Menu from Microsoft Word's Help on inserting headers and footers

Although inserting headers and footers is the main task, the topic really has 11 related tasks:

Insert the same header or footer on each page
Make the first page header or footer different from the rest of the pages
Use no header or footer on the first page
Make the header or footer different for odd and even pages
Make the header or footer different in each section or chapter
Change the contents of a header or footer
Insert a page number
Insert the file name of the document
Insert the document title, author’s name, or other document property
Insert the current date
Remove the header or footer

The author could have created 11 separate topics. Do you agree with Microsoft’s decision to group all of these subtasks into the same topic? Or would you rather explore each subtask as a separate topic in a table of contents?

Although the practice of single sourcing encourages chunking of tasks, if you won’t be reusing the subtasks or related tasks independently, there’s little reason to separate them out into discrete topics. Forcing all of these subtasks into separate topics would severely bloat the table of contents (TOC), rendering it not only less usable, but also more intimidating. Your application’s apparent complexity would magnify.

Separating each subtask into its own topic often forces users to click in a non-linear pattern from topic to topic as they search for the right task. This nonlinear clicking can give users a headache. It’s part of the reason why reading online is more strenuous than reading a book. Books provide more of a hierarchical layout and logical progression of ideas. In contrast, the web is a scattered maize.

Consolidating subtasks into one topic also improves the user’s ability to find topics. With fewer topics in the TOC, the user can actually browse the TOC and find the right topic. But even if the user reverts to keyword searches, the longer topics will have greater keyword density and more likely rise to the top in search results.

I sent a question across Twitter the other day asking whether anyone had done research into this issue, and Brenda Huettner pointed me to a Web Usability Guidelines reference book. Chapter 8 echoes Brenda’s response that “it depends.” The authors say that older people are slower at scrolling, but comprehension may be better because the user remains on the same page. Here’s an excerpt:

Guideline: Use longer, scrolling pages when users are reading for comprehension.

Comments: Make the trade-off between paging and scrolling by taking into consideration that retrieving new linked pages introduces a delay that can interrupt users’ thought processes. Scrolling allows readers to advance in the text without losing the context of the message as may occur when they are required to follow links.

However, with pages that have fast loading times, there is no reliable difference between scrolling and paging when people are reading for comprehension. For example, one study showed that paging participants construct better mental representations of the text as a whole, and are better at remembering the main ideas and later locating relevant information on a page. In one study, paging was preferred by inexperienced users.

Sources: Byrne, et al., 1999; Campbell and Maglio, 1999; Piolat, Roussey and Thunin, 1998; Schwarz, Beldie and Pastoor, 1983; Spool, et al., 1997; Spyridakis, 2000.

In other words, each time a page loads, you interrupt the user’s thought process. By remaining on the same page, the user can better grasp the concept as a whole.

Thanks for the resource, Brenda! In the studies, the content consisted of web pages rather than help material. Some of the examples for scrolling depict long, sophisticated pages — quite a bit more hairy than the Word example above. Still, I agree with the general findings and think they apply to help authoring.

My colleague Ben Minson, however, raises an important objection to long topics. He says,

In reality, people don’t want long topics. They want to think that procedures are short and simple. Long topics intimidate people and make them reluctant to consult the documentation in the future. (“Long Topics: A Help Author’s Crime Against Humanity“)

I agree that no one wants to be confronted with a massive topic when all they need is information to complete simple task. However, adding a quick topic menu at the top, similar to the following image, seems to solve that problem, doesn’t it? The user can jump immediately to the relevant topic, rather than meticulously scrolling down and checking each heading.

[image title="Example of a Quick Menu" size="full" id="2017" align="left" linkto="viewer" ]

Overall, in my experience, it’s easy for a help’s TOC to grow successively larger as you think of more and more scenarios, possible tasks, and concepts to explain. But if you reach the end of the project and see that your initial 50 topics have grown to 250, I think something’s wrong. Most applications aren’t that complicated. When users expand the TOC and find a seemingly infinite number of topics, it’s the equivalent of the disheartening “thud” from a long printed manual.

Table of Contents: Creative Examples | Smashing Magazine

Tom Johnson — Sun, 03 Aug 2008 07:07:48 +0000

Table of Contents: Creative Examples | Smashing Magazine.

I'd Rather Be Writing » table of contents

Topic-Based, Hierarchical Navigation [Organizing Content 5]

Blog Sponsors

Imposing Order Versus Observing Order [Organizing Content 4]

Organizing the Periodic Table of Elements

Limits of Logic

Blog Sponsors

Things Fall Apart, The Centre Cannot Hold [Organizing Content 3]

Technical distractions

Non-linearity and linearity

Crumbling organization

More content, but no space for it

Blog Sponsors

Introducing Project Swordfish [Organizing Content 2]

Blog Sponsors

Leaning Towards Longer Topics and Shorter TOCs

Table of Contents: Creative Examples | Smashing Magazine