Search results

Where Topic-Based Authoring Fails: End-to-End Scenarios

by Tom Johnson on May 25, 2011
categories: findability

After my Summit presentation about breaking out of topic-based hierarchies, a lady named Ursula came up to me and said she was tired of topic-based authoring. I asked her what the alternative was. She said she's often more interested in seeing an end-to-end process rather than a specific task. This reminded me of a tutorial on in which Deke McClelland, the trainer, showed how to make a black cat, with the eyes, curly whiskers, gradients, and all. The process involved probably 10 different tasks.

Black cat tutorial
This tutorial walks explains how to make this black cat. It relies on about 10 different techniques used together. (The full tutorial is at, which requires a subscription to access.)

Ursula has a good point. The problem with topic-based authoring is that many times these tasks don't mean a whole lot in isolation. Like drawing a cat in Illustrator, you have to rely on a number of different tools and techniques working in combination, sequence, and tandem. You could separate out all of these tasks out from the whole, but when you do, it's hard for the user to see how the tasks are used in combination with each other.

This kind of organization might be labeled end-to-end scenario organization. The problem is that the specific scenario may or may not apply to the user. With the example I mentioned, it's great if you're drawing a cat. But what if you're drawing an elephant, or a human? Surely some of the techniques may apply, but users may not realize it while scanning topic titles.

Traditionally we teach people individual skills and tools and then let them apply them in different sequences and combinations for their particular task. The problem with this topic-based organization is that it doesn't teach you how to use the tools in combination with each other.

Showing an end-to-end scenario can't really be solved with the metadata and query method that I explored earlier. To summarize, my direction so far has been to chunk help material into small pieces, attach metadata to each piece of information, and then sort it based on different metadata queries. But all that method really does is return a bunch of lists. Those lists may not be that helpful to your users. What they may find more useful is a topic that shows an end-to-end scenario, which is not something you can feasibly show through any kind of automated process.

Other types of organization also fall short with the metadata queries. A cousin to the end-to-end scenario is the story/workflow-based organization. Describe a typical workflow scenario for a particular role, linking to each topic as it appears in your story. No automated retrieval process can pull results together into a story, yet this format might speak in a more real way to the user.

Another organization that doesn't really work well with metadata is a level-based documentation. Think of karate levels, where participants master a specific skill and then move up to the next level. I mentioned an earlier example of this from Kathy Sierra and her Pirelli horse manuals. As a user masters one set of tasks, you push that user up to the next level. This level-based documentation is much more sequential in a beginner-t0-advanced way. It builds on certain skills and allows the user to advance to the next level after achieving competence at one level. It's hard to imagine this system achieved in an automated way. Yet this type of organization might be much more helpful to users.

Overall, I think I may have overemphasized the usefulness of metadata in sorting information. In a presentation at Confab, Steve Rosembaum warned about the inability of computers to curate content in useful ways. He says that computers just don't do well at collecting, organizing, and contextualizing content. You need a human being to do it. I think he's right. Some of these more useful and interesting forms of content curation are only possible through a manual, thoughtful process.

That said, there's no reason why you couldn't do both, providing queries based on metadata as well as arranging the content in custom ways.

About Tom Johnson

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.