Misconceptions about Topic-Based Authoring

by Tom Johnson on Jul 31, 2012
categories: findability

So far I've been exploring different ways to organize content to increase findability, but I haven't examined perhaps the most fundamental technique of all that affects how we organize and shape our content: topic-based authoring.

What does topic-based authoring mean? Somewhere in learning how to be a technical writer, I was taught or assumed that topic-based authoring meant kind of the following:

When you're exploring software documentation, make a list of all the tasks you think users would do with the application. Let each of these tasks be its own standalone topic in the help. Include a brief description of the task and a series of steps on how to perform it. You can write in any order.

When you've finished writing all the tasks, arrange them in a logical way in the table of contents for the reader. Group like tasks together in the same books.

You can single source the content from online help to print, as long as you can fine-tune the styling. The reader most likely won't read the manual or online help cover to cover, but will read the topics that matter.

This was pretty much my idea of topic-based authoring. Everything is an individual, standalone topic that you can mix and match in whatever order you want, almost like a deck of cards.

Recently I have started to rethink this approach. Reading one of my single-sourced printed manuals (which I wrote using this approach) from cover to cover, I found it a disappointing read. As I turned page after page, the content was redundant in places, conceptually hard to follow, choppy, and at times seemingly random in its organization

My experience made me wonder if perhaps my “topic-based authoring approach” (if indeed that's what it is) led me astray. Maybe the whole paradigm is short-sighted as a technique for writing?

Topic-Based Approaches for Other Writing Scenarios

It's not surprising to me that a topic-based approach has shortcomings as a technique for writing. Can you imagine any writing scenario where you write a bunch of pieces of discrete information and then mix them in the right order, or into multiple orders, and actually get a readable output? I certainly didn't write this blog post that way.

Let's say you're writing a novel. With your tech writing background, you decide to follow a topic-based approach. You draw up seven character sketches, describe five scenes, and write out a dozen action plots. Now you lay them all out on index cards and start mixing and matching the characters, scenes, and action plots until you get the organization just right. Then you click print and voila, you have a really poorly written novel.

Do Readers Care?

I think that a lot of readers will argue that no one reads printed manuals anyway. Long PDF manuals are dead! Readers merely search for specific questions. They jump in and jump out of help almost in the same breadth. To say that the cover-to-cover reading experience of a manual is poor is like saying the horse-riding experience from Salt Lake City to Provo is really shoddy and almost unnavigable. Sure, because no one rides horses for transportation in cities anymore!

But do you know why no one reads long manuals? In part, maybe it's because user manuals are such poor reading experiences. In fact, they are actually unreadable. You'd need the patience of a dead owl to get through some of them. When we single source our conglomeration of topics into a linear print experience, it just doesn't work. About the only situation it works is the situation that users have adapted to – quick searches, skimming for the right information, and then closing the help file.

Notice I wrote "adapted to." Rather than assuming technical writers fit their content to the skimming, non-reading behavior of users, what if it's the other way around? Because of the content, users have developed this behavior to adapt to it. If the help content were more readable and engaging, following a clear narrative flow, I bet more users would actually read the manual.

From Short Topics to Lengthy Articles

I think I could write a lot better help material if I discarded the topic-based authoring approach. If I instead approached technical instruction as a series of articles, which fit together coherently, somewhat like on a blog, I would do a much better job.

Approaching help content as articles is an idea Mark Baker explores in his post, What is a topic? What does standalone mean?  Mark references a post from Scott Nesbitt, who notes that Google writers call their help content “help articles” rather than “topics.” Mark says,

This points at a very different way of looking at what it means for a topic to stand alone. If the help is a set of articles, an article is something that can be read on its own. It is not part of a larger manual. It stands alone. That is, it stands alone not merely by existing separately, but by functioning separately.

He goes on to reflect on what standalone means. To some extent, everything fits in into some larger system. Take brake calipers, for example. Brake calipers are a unique part, for sure, but they are useless unless they fit into a brake system, and that brake system attaches to wheels, and connects to the engine and brake pedal, and so on.

The idea that everything is interconnected isn't new. Let's take a minute to reread John Donne's famous poem, "No Man Is An Island."

No man is an island entire of itself; every man

is a piece of the continent, a part of the main;

if a clod be washed away by the sea, Europe

is the less, as well as if a promontory were, as

well as any manner of thy friends or of thine

own were; any man's death diminishes me,

because I am involved in mankind.

And therefore never send to know for whom

the bell tolls; it tolls for thee.

While no man is an island, we do function, for the most part, somewhat independently -- just as an article or a web page functions somewhat independently, while also connecting into other concepts and fitting into a larger system.

Mark summarizes this interplay between standaloneless and interconnectedness:

To say that an article stands alone is to say that it is not designed to work as part of some larger information product. But neither is an article expected to work in a complete information vacuum. Indeed, many of the articles you find online are useful precisely because you can highlight a term or concept you don't understand and select “Search Google for…” to find more information. The article stands alone not because it is entirely self-sufficient, but because it exists in a rich information environment that the user can call on to further their understanding. It stands alone not because it depends on nothing, but because it depends on everything.

I think I could write a lot better user guide if I followed the same writing approach that I do on this blog than I do following a topic-based approach with a help system. On this blog, I write articles. They often include subsections. The articles are intended to be read as a whole. The articles don't necessarily flow from one article to the next, but when I write a series of articles, they sometimes do. For example, my Seven Sins of Blogging series flowed together, as did my From Overlooked to Center Stage series, and my 7 Steps to Getting a Job in Technical Writing post.

Creating Readable Content

If user guides are going to be readable, they should be written from a more comprehensive, beginning-to-end conceptual point of view. The real heart of technical instruction doesn't lie in the step-by-step how to information, the 1-2-3. It lies in understanding concepts and how they work together to produce an end. This focus on the conceptual interplay of the parts should drive the technical writing experience, both from a reader and writer's point of view. Procedures are more like footnotes. As soon as the user understands the why and the what and the who and the where, the how is merely a mundane detail.

In fact, you could even omit many of the tasks from a printed user guide, choosing just to include the main tasks. The ancillary tasks can simply be referenced to an online location.

Here's how I think a manual might be laid out:

1 – Big Concept

* task, task, task…

2 – Big Concept

* task, task, task…

3 – Big Concept

* task, task, task…

4 – Big Concept

* task, task, task…

5 – Big Concept

* task, task, task…

The real focus in help should be on expanding the concepts, and the concepts should be written in a way that fits together coherently. The concepts drive the flow of the content. The tasks can perhaps be organized in collapsed drop-down hotspots below the concepts. When a user needs that information, it's a matter of merely following the steps. And I believe tasks can more or less be written in any order, following a topic-based approach. But not concepts.

When you have a couple of hours, try printing your user guide and reading it cover to cover. It's nearly impossible to  assess the coherence of a printed user guide except by reading it all the way through. As you read through the content, skim the tasks – the mere details. But read the concepts like you would an article, and follow your gut reaction. Does it make sense as a whole? Is it coherent? Or is it a jumble of rusty parts forced into the same bag and parading as a "guide"?

Tools, Not Information Design

I've titled this post "Misconceptions about Topic-based Authoring" because I'm not entirely sure if topic-based authoring is at fault, or my conception of what topic-based authoring is or should be. In his post The Tyranny of the Terrible Troika: Rethinking Concept, Task, and Reference, Mark Baker explains that DITA, a topic-based writing methodology that focuses on concept, task, and reference topics as the three building blocks of content, doesn't prescribe any method for assembling the topics in readable ways. Mark says,

If there is a problem with DITA, then, it is not that it lacks a theory of information design. The problem is that many people actually believe that it does have a theory of information design, and that that theory can be summed up in three words: concept, task, and reference. But a theory for breaking content up into pieces is not a theory of information design unless it also includes a theory of how the pieces should go back together.

I had assumed that assembling topics was simply a matter of grouping like content together. But information design is much more than that. Writing this post involved more than arranging discrete, independently written paragraphs into an order that made sense. The order of the paragraphs was driven by conceptual flow from the beginning, and then refined as a whole again and again.

If DITA lacks information design, then what we truly need in tech comm right now is a theory that tells readers how to assemble information in readable ways. This is what I've been trying to solve when I started this whole series on organizing content for findability. It's the missing puzzle piece in tech comm methodology. How are you organizing your content?

For more reading on this topic, I recommend the following articles from Mark Baker's site:

• What is a topic? What does standalone mean?
• The Tyranny of the Terrible Troika: Rethinking Concept, Task, and Reference
• Frankenbooks Must Die: A Rant