Adobe Robohelp

Get new posts delivered straight to your inbox.

Subscriber count: 3,220

Adobe Robohelp

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

May 25, 2011 • 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.

Get new posts delivered straight to your inbox.

Subscriber count: 3,220

About Tom Johnson

Tom Johnson

I'm a technical writer based in the California San Francisco Bay area. Topics I write about on this blog include technical writing, authoring and publishing tools, API documentation, tech comm trends, visual communication, technical writing career advice, information architecture and findability, developer documentation, and more. If you're a professional or aspiring technical writer, be sure to subscribe to email updates using the form above. You can learn more about me here.