Misconceptions about Topic-Based Authoring

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.

Help as non-linear, independent topics

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.

Help as a series of articles

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:

Madcap FlareAdobe Robohelp

By Tom Johnson

I'm a technical writer working for the 41st Parameter in San Jose, California. I'm interested in topics related to technical writing, such as visual communication, API documentation, information architecture, web publishing, JavaScript, front-end design, content strategy, Jekyll, and more. Feel free to contact me with any questions.

  • Nicky Bleiel

    Timing is everything, Tom. You asked how I am organizing my content — I just posted this last week: “How to Structure a Help Project” http://our.componentone.com/?p=32044 I think this method (taken along with Part 2 of the post) helps eliminate redundancy, and improves flow.

    • http://idratherbewriting.com Tom Johnson

      Thanks Nicky. I checked out the posts. Very helpful. I like that you include the UI topics for context-sensitive help. In looking at this screenshot, it seems you put all the context-sensitive UI topics inside their own bucket/folder. If you name the topic the same name as the dialog box (but omit the term “dialog box”), how do you associate the topic with a similar functional topic?

      For example, if the dialog box is “Widget Configuration dialog box,” and the related task is “Configuring the Widget,” how do you organize these two topics in the TOC? Do you create two separate topics, one called “Widget Configuration,” and another called “Configuring Widgets”? If a user searches for the phrase “configure widget,” which topic appears? Would it be confusing for the user to land on the UI context-sensitive topic rather than the task topic?

      I also noticed that you include content at the book level, so that when a user clicks a book (or bucket), a conceptual topic appears automatically. Other help systems I’ve seen don’t do anything when a user expands a book (or folder). The user has to select a topic within that book before content appears. Can you share your reasoning for that?

      Finally, I noticed you use gerunds in topic titles. With gerunds, how do you differentiate between concepts and topics? It seems like gerunds straddle the fence with the topic type. Other styles (such as Microsoft’s Manual of Style, 4th edition) use noun phrases for concepts and commands (e.g., “configure”) for tasks. If you have any particular philosophy about topic titles, I’d be interested to hear it. Thanks again for commenting.

  • Janet

    Excellent post, Tom. I think many writers misunderstand topic-based authoring and we’re also losing track of what our users are actually trying to do with the information.

    • http://idratherbewriting.com Tom Johnson

      Thanks Janet. I appreciate your comment.

  • Jørn A Hansen

    As mostly being a user/support-person – not author – but with an interest in Information Design/Architecture I find this and related posts and comments very interesting. And I start wondering why the “Franken-documents” I’m often offered gets we wandering so much in circles wondering where the golden nuggets are.

    I like the idea of clustering in “islands” around bigger knowledge areas (big concept, task, task, task). Maybe it could even be turned the other way around with a very brief map of what this island has to offer and then let me find the right detailed task? At least for help delivered through e.g. modern web media where links inside one bigger page is “cheap and easy” to implement…

    See slide 31 in http://www.slideshare.net/CathyMoore/design-lively-elearning-with-action-mapping/31 where I got some of my inspiration from …

    Admitted this is not from the technical documentation area but training/(e)learning. But I guess the goal is somewhat similar: Let me as a user get help to reach the goal I have in mind and get on with my life! Then *if* I got curious and decide I want deeper knowledge I can read on and dive into the overall concept – or specific sub concepts

    What do you think – would this fly? Or am I falling into some sort of beginners trap here?

    • http://idratherbewriting.com Tom Johnson

      Jørn, thanks for sharing your insight. I think your description of clustering information around bigger islands, or providing a map of the island and then including detailed tasks associated with that island, aligns with what I’m recommending here as well.

      Providing users with options for deeper knowledge is a good strategy — the key word here being “options.” Too often I think we present readers with too much information up front, rather than letting them choose to drill down into more specifics and details as needed. Overall, I like the metaphor of the islands.

  • http://everypageispageone.com Mark Baker


    One of the topic types I use in Every Page is Page One projects is what I call a pathfinder topic. Some user’s know just what they are trying to do and go right to it. Others need to get the lay of the land. A pathfinder topic is for the latter type of user.

    Very much like what you describe, a pathfinder topic essentially takes a high level task area from the user’s world (authoring, configuration, development, etc) and show how the product handles that area, pointing to more specific task topics to deal with the details of how things are done.

    In many books and manuals, the only way to get that kind of pathfinding information it to read the book as a whole. If the book is burst into topics, the pathfinding information can disappear altogether. Without pathfinder topics, a topic-based information can become impenetrable to the new user. I therefore regard them as essential to an Every Page is Page One information design.

    • http://idratherbewriting.com Tom Johnson

      Mark, thanks for commenting. Also thank you for all the great articles that I referenced in my post.

      I like the idea of “pathfinding” topics. Is a pathfinding topic similar to a landing page (to use other lingo)? It would be great if you had any examples online that I could check out.

      This past week I pulled out all of my concept topics and pasted them in a Word document, and then I read them front to back over and over, rearranging them here and there, removing or adding sentences, and basically working on the content similar to a blog post. It was an interesting exercise. I think it helped me a lot to just focus on the conceptual information and its flow.

      I now plan to reintegrate the tasks where relevant. I have an upcoming post that describes my strategy on doing this. Basically, I plan to integrate the tasks as collapsed hotspots below the concepts.

      So that the tasks aren’t pushed down too far, after two paragraphs of a conceptual explanation, I’ll add a “Read more” link that will expand the concept if the reader wants to read it.

    • J. Tillman

      Mark, you have used the term pathfinding. How close is this to a similar concept: troubleshooting? Both seem to involve figuring out how to get to the right spot to do or read something. In my mind they may be the same thing. What’s your take on this?

  • http://www.sesam-info.net Jonatan Lundin

    Topic based authoring is not a must by itself. I argue that you have to know the fundamental behaviors of users to know what type of information to develop and the “content resolution”. A consequence of knowing the information behavior can be to chunk up content in pieces, called topics, articles or whatever. Lets look into the information behavior from a broad perspective.

    Why do companies develop technical products (hardware, software etc)? Frankly put, since they have recognized that people on certain markets have needs to solve problems, requirements or desires. Why do anyone buy and use a technical product? First of all, people have a need to solve problem, requirements or desires. Since people (users) have understood that a product can help them solve a problem, requirement or need they are willing to use it. Technical products are designed to be used to deliver an outcome that solves a need. Users use the product to make it deliver the outcome that solves the need. Users are not doing tasks without a goal in mind; no user is doing tasks just because it is fun to do them. Technical communicators are too much focusing on tasks as single entities without finding out why users are doing tasks.

    How do users go about using the product? As dictated in minimalism, users are active and goal oriented. Most users start to use the product based on what they know, hoping to be successful. Users jump out into the unknown. If users knew exactly how the product should be used to deliver the outcome, no information is needed. But perception and semantic knowledge of users are different and they interpret a product differently. When users see a product UI they form a mental model about the product; what it can do and how it should be used. In most cases they act upon this mental model.

    Problem occurs when the mental model differs from the actual design (what the product can do and how it should be used to deliver the outcome). Now, this is a simplified version of reality. Users are different. Some are methodical and know that they do not know and therefore wants information before starting to use the product. Some are irrational and do not know that they do not know. When users are stuck, they are in a problem solving situation and try in many cases to find information to solve the problem. Users are located in a search situation.

    User asks a question when in a search situation. They want the answer quickly and without putting in a lot of effort. In a topic based world, a topic shall answer one user question. So what questions do users ask? And how do we get to know them before they are asked (as in a predictive, pre-release approach to documentation)?

    A search situation can be classified from various facets. First of all, users are using the product to solve a problem, need or requirement as said in the beginning. So we need to know what problems, needs and requirements the product is designed to solve (the user primary goal). A typical product can be used to deliver many outcomes (called meaningful result statements – MRS – in SeSAM). The “Big concepts” you are depicting in this post is the MRS. SeSAM includes a methodology to identify the many MRS of a product.

    A search situation can also be classified from the task the user is trying do to. A user wants to get the product deliver the meaningful outcome as quickly, easy, cost efficient and securely as possible. This involves different tasks as, installing, configuring, using, viewing, customizing, troubleshooting etc. These tasks are the secondary goals and each MRS does have a number of secondary goals associated with it. There is a special secondary goal where the users want to learn and understand the MRS, since the user has recognized that s/he has misunderstood the product design. The “task, task…” etc you are describing for each Big concept is the secondary goals in SeSAM terminology. Each secondary goal, there are 8 pre-defined in SeSAM, is associated with a number of subgoals which are the actual questions. SeSAM pre-defines some 80 subgoals in total.

    The classification of a search situation using the search situation facet taxonomies do help you to narrow down and identify the questions you assume your users are asking. The different search situation facet taxonomies are used to build a matrix called the MRS matrix. Let’s say your product is designed to solve 10 primary goals meaning that it is used to deliver 10 MRS. For each MRS you have identified 8 secondary goals and that each secondary goal is associated with 10 questions. Then you need to provide 800 answers which can be managed as DITA topics, articles or whatever form you choose. When users get the answer to one question in a search situation it may give rise to another question (chaining). So users may explore some 10 answers in a search situation.

    Now an answer must be findable. A pool of 800 answers, as LEGO bricks randomly placed in a box, is not helping the user. Again, the search situation facet taxonomies are used to build a search user interface, – the intermediary – for example as a guided faceted search environment. This can be done since each answer is classified from a facet in each facet taxonomy. Answers are not organized in a static arbitrary hierarchy, only classified (where the value used is considered metadata in the topic). This approach means that you as a technical communicator are not managing user manuals but managing questions and answers. And this approach means that technical communicators can integrate what they are doing with the answering processes of support teams.

    There are many aspects in SeSAM not considered here. SeSAM includes 8 pre-defined search situation facet taxonomies. Two of them were elaborated on above (primary and secondary goal). A search situation can also be classified from which operating environment the product is used in, the product interface being used and many others. Also, a user must be assumed to have certain knowledge. The consequence of assuming a knowledge level is that you do not need to write certain answers since it is assumed that the user know the answer.

    BTW: Tom, it is not possible to submit comments on previous post.

    • http://idratherbewriting.com Tom Johnson

      Jonatan, thanks for your comment. You wrote, “Technical communicators are too much focusing on tasks as single entities without finding out why users are doing tasks.” I definitely agree with this. In some instances, users just want the quick details of how, and in other cases, they want the details of why.

      You mentioned a scenario where a tech writer ends up creating 800 topics to answer various goals. This would obviously lead to topic bloat in the table of contents. Your solution is to provide a dynamic faceted search system that provides filters based on various taxonomies or metadata (presumably the search facets). I’m curious to know how you implement dynamic faceted search in the real world. I’ve never seen a help system that offers faceted search.

      Also, re commenting on previous posts, I didn’t turn this functionality off, but I did switch themes. Are you not able to comment on any previous posts? Which post were you trying to comment on? I’ll investigate what’s happening. Thanks for the note.

      • http://www.sesam-info.net Jonatan Lundin

        Hi Tom,
        A table of content referencing 800 topic is not designing for findability, that’s for sure.

        A simple mock-up of, what I call a guided faceted search portal, is available in http://www.sesam-info.net/GuidedFacetedSearchMockup_TrafoProt.pptx. Open the PPT presentation in slide show mode and click on any clickable link. Not all, what appears to be a link in the interface, are clickable.

        Imagine you’re a professional industrial worker, trying to figure out how to operate, configure or use a relay called the TrafoProt. You decide to use the TrafoProt knowledge base to find the answers. The knowledge base is the power point mock up.

        The principle behind a guided faceted search is that the SUI is dialoging, meaning that it asks a question to the user and gives a number of options to select from. This principle of interaction is following what you get when seeing the doctor, talking to a librarian, setting up a computer game, talking to a senior (maven) expert etc. The “someone” is asking and presenting options and you have to make a selection. The actual answer is given in the right most frame. This mock-up SUI is what I previously called an intermediary.

        The idea behind the SUI is based on many principles; feedback, progressive disclosure to not overload the user short term memory, “learn-as-you-search”, a reversed taxonomical approach to design etc etc.

        A note is that the mock-up currently provides a very simple interaction and contains maybe too much text in some pages. But it is the principle that counts. I think you get the idea anyhow.

        The blog post I was trying to reply on is “Why Do We Need Navigation At All?” I can’t reply to Mark Bakers reply on the 24th of July.

  • http://madaboutmedia.timpenner.ca Tim Penner

    I’d like to carry Mark’s notion of a pathfinder topic a tad further. Consider your example of brake calipers and their role in braking systems that a general knowledge of which helps to understand how to service brakes. This is pretty good as far as it goes. But there’s a lot more to braking systems than how or whether the parts connect. There’s also a more general discussion of hydraulics that you can’t totally ignore when becoming the mechanic who’s going to take responsibility for peoples’ automobiles stopping. There’s also a vast level of complication in the interaction with the drive system for anti-lock braking systems and vehicles that actually take control of the vehicle using brakes and drive system components to negotiate tricky road conditions. This all goes to say that a bit of glue will go only so far.

    This is where the place of an information tidbit (call it an article or topic, call it concept, procedure or reference) in the whole subject domain becomes quite important. When I think about that, I see a vast network of everything that humanity has ever known, connected through myriad, multilevel links based on all kinds of parametric channels all leading inexorably to calipers . By “parametric channels” I mean the subjects or domains of the links themselves. For example, “safety”. The materials that brake pads and shoes are made of is a great concern because it has been found that they often contain asbestos. When pads and shoes break down, the dust that accumulates in wheel drums is dangerous for mechanics. Because pads are attached to calipers, it matters whether you can obtain replacement parts that are safe to work around or you need proper means for handling the hazardous materials. “Safety” links could bring us to all kinds of interesting material, from automobile hoists that work well to tools that help mechanics avoid busting their knuckles.

    Many of us have waxed poetic about the matter of content categorization. We are smitten by the idea that ”everything is miscellaneous”, but, frankly, in a subject area that doesn’t have a vast public strolling through it, someone needs to make some connections. Take my example of the universe of knowledge network with calipers at the middle: I also see the links coloured to reflect their affinity to calipers. Let’s say I’m writing an instruction manual for brake mechanics. I place a little knob at the bottom of the display programmed to control the colouring of the “practicality in brake maintenance” parametric channel. At the knob’s lowest setting, the entire network is bright red because all knowledge connects. At a high affinity setting, there is a small cloud of brightly coloured links quite close to calipers, which circumscribes automotive engineering and maintenance. Eventually, the knob’s inability to read the consumer’s mind starts to show, because it doesn’t know the kinds of affinities that make sense to him or her personally. But, ultimately, there is a handful of topics, the nodes of the network, that the mechanic should probably read.

    I’ll wrap this up. I started off by dismissing the idea that a bit of glue doesn’t really do it. I would prefer to see us, the purveyors of explanation, come to terms with useful taxonomies (taxa ?) in our subject domains and provide paths for people to really see where to go given the object of their immediate concerns. Can we predict such things? It wouldn’t be impossible but likely expensive. I recognize that Mark Baker’s EPPO can attend to this by linking topics as they are assembled, but I want to see the glowing network explicitly without having to spend the next 10 minutes clicking around and trying to remember where I’ve been. My affinity control knob is a bit of fantasy. So, the question is: could we explicitly portray knowledge domain networks that can be traversed by non-technical information consumers?

    • http://madaboutmedia.timpenner.ca Tim Penner

      Gotta add a teeny bit more.

      A really good book on a subject is just such a domain portrayal. And the beauty of it is: you can zoom in and out, that is, read about something and spontaneously answer the question, “where and I?”, by seeing where you are in the table of contents at the front of the book. And then when you find a word or reference you want to follow, then follow it using the fabulously well-built index at the back. I’ve read such books, but only a few.

      I do recognize that tables of contents and indexes (indices ?) are like railroads. And that the ocean is almost invariably a better place to surf and swim. But, sometimes, there are articulate domain experts who do a really good job.

    • http://idratherbewriting.com Tom Johnson

      Tim, thanks for your comment. One definitely could expand a topic into larger conceptual connections, as you point out. But it seems that one has to draw the line somewhere and decide where to stop making connections. I think a general article on safety, with some pointers on where to go for more information would do it.

      If we start expanding the scope too much, we lose the benefits of a focused topic. It’s kind of like with essay topics. Sure, if you’re writing about the civil war, you could expand into war in general, and conflicts between humans, and psychology and so forth. But expanding into larger and larger connections dilutes the power of a more focused message.

  • Tammy

    Very, very good post. The concerns you identify about single-sourcing and topic-based authoring are the ones I have had for several years now. Even the book I read about DITA, which was written in DITA, had some pretty significant examples of “broken flow” – where examples didn’t make sense based on the previous item and transitions were almost nonexistent.
    I have no doubt that topic-based writing, like other approaches, can be done well. However, the pitfalls and the tendency to do what’s quick and easy are big problems that anyone who embraces the approach needs to keep in mind.

    • http://idratherbewriting.com Tom Johnson

      Thanks for commenting, Tammy. Just curious, what DITA book were you reading?

      I certainly think that when technical communicators apply a topic-based authoring approach, which may be appropriate at times for technical material, to a book-reading paradigm, the results aren’t what they expect. As you say, you end up with broken flow.

  • http://writetrends.wordpress.com Patty Blount

    As I read this post, I thought “So we should write content like a blog post.” And then you made that exact point later in this text.

    My company recently began a similar endeavor… writing scenarios that collect all the tasks and concepts required to solve a specific business problem and delivering them in a standalone article. I’m thoroughly enjoying this approach because it forces me to constantly keep the big picture in mind: what had to be performed first, what must come next? Even though my readers will likely not read the entire manual sequentially, there is nevertheless still a sequence of activities that must be performed in a specific order to successfully use the products I document.

    This point was never as clear as during an SAP class I taught several years back. I designed, developed and delivered a course on building product codes called material masters. Despite analysis and a hefty review cycle, it was not clear until the pilot class that I’d made a huge miscalculation. I’d failed to keep the large picture in mind and delivered a series of tasks.

    My class did not know how to collect those tasks in a manner that could solve their problem: How do I create a sellable product?

    In this class, I’d provided every task required but I never connected them in the proper sequence. They were organized in a more old-fashioned manner: Creating material masters, creating sub-assembly codes, creating shippable codes, creating packing lists.

    After the pilot, I corrected the flaw by drafting flowcharts of the overall problem and solution, and adding decision branches into the topics themselves.

    It’s a lesson I never forgot.

    • http://idratherbewriting.com Tom Johnson

      Patty, thanks for sharing your experience. I like your emphasis in keeping the larger picture in mind. I agree that we often become lost in the details of the tasks, and while we may have the larger picture in mind as technical writers, our users often don’t. All they see are myriad disconnected tasks that are pieces to the puzzle but not the whole picture they need to assemble it.

  • Fil

    Nice article. I haven’t been a tech writer for long but have had a varied career writing a variety of correspondence. At the end of the day, it seems to me, that story is king. What we learnt in primary school about having a beginning a middle and an end to any writing is still crucial. Sure it may not necessarily be a story we want to tell, but if the story of a help article flows in this basic format it makes it easy to answer the questions who, what, where, when and even the how.

    • http://madaboutmedia.timpenner.ca Tim Penner

      It certainly may be that story is king in many lands. Ask Daphne Grey-Grant, for example. However, in technical communication land, it’s probably better to cut to the chase. One syllable too many and no one will read it.

    • http://idratherbewriting.com Tom Johnson

      Fil, thanks for bringing up story. I agree that story is king. It’s a structure that makes most any kind of writing work well.

  • http://@saruhrosen Sarah Rosen

    Really fascinating article and great comments. I’m very new to tech writing, as in fresh out of the gate, but I’d like to chime in based on my current experiences:

    I am currently migrating an “Administrator’s Guide” for a very complex data capture and monitoring system for mobile networks. The existing legacy doc is dense, redundant and difficult to navigate. To migrate, I use the 5 W’s and how (who what when where why and how) to try and help me sift through the information. This has helped me minimize and restructure, but I am still left with the issue of “information flow”, or as Tom described it as “information design”.

    I tried to design, or organize the information in relation to the When and What and How “Ws”. Which means that the information is organized first in relation to the frequency of information used (when), then by what the information is is referring to (what software/hardware tools), and then How. This means I do a lot of information grouping. The design isn’t too bad, at least, that’s what I’ve been told, but users are saying that the doc is not as effective as it could/should be. Why?

    Well, frankly, the information is choppy as Tom accurately describes; and this despite the fact that it’s task-oriented, minimalistic and based on the Every Page is One Page approach that Mark mentions. So where is the problem/dissatisfaction coming from? I think it’s content fluidity, or flaws in the design; the ensemble.

    Which brings me to the point that Mark made about path-finding. As mark describes, “Without pathfinder topics, a topic-based information can become impenetrable to the new user.”

    This is so true. And as proof, I can tell you that the Admin Guide users (and not just new, but also intermediate and advanced users) asked me to include a list of the most common information being consulted for the Administrator’s Guide (whether task, topic or reference). I found this to be a strange request seeing as how “common” can mean different things depending on the user (as Jonatan discusses in his comment). Besides, users can use keywords to search for the information they need (in PDF, Online Help, etc.). Not to mention that the TOC is well-enough structured, titles are appropriate, etc… So why make a list?

    Well, the customer is always right. So, I thought about how I could meet user demands/needs without adding redundant info. Then, it came to me. The user wasn’t asking for a simple list, he was asking for a more direct path to the information that he needs. The user doesn’t want to have to search, or sift through results or peruse a TOC to find info; and titles don’t tell you what depth of information you are going to find in a specific topic… Okay, so the user is right. There needs to be an information path.

    So, how do I make a path? What kind of path is the most effective?

    Grouping or linking information is not enough. I needed to bring the information together without weighing-down the content. In brief, I needed to make “islands”, as Jorn mentions in reference to Donne’s poem. (Donne means ‘give’ in French btw from the verb “donner”).

    For me, the island analogy is equivalent to information pit stops that tell the user he is on the right track and that the next stop is near-by. The user can regroup, clarify his trajectory and reevaluate his objectives. So, I made pit stops.

    I decided to use concepts that briefly explain in greater depth the content matter, subject, etc. and then I include a list linking each related info/subject/task/etc. to the appropriate information in the Guide. I am not sure if these concepts (pit stops) are effective. I am still waiting on feedback. However, I can say that the “islands” or “path-finding” or pit-stop approach, as I call it has helped me write more coherently in relation to the ensemble.

    There are certainly several solutions to the choppy effect related to misconceptions of topics and what “stand-alone” means. I have read articles on the use of “Use Cases” and more narrative approaches in tech docs, which may be effective. However, the issue still remains: How do we maintain coherency in a topic-based stand-alone or every page is page one approach without losing sight of the fact that a document containing many pieces is still a whole, and should be treated as such; even when single sourcing. Are islands the answer, maybe maybe not. But there is only one way to find out. Poor users, always as the brunt edge of the learning curve…What would we do without them?! 😀

    I appreciate the opportunity to discuss this issue with you all and look forward to hearing how others have dealt/are dealing with this issue.

    • http://idratherbewriting.com Tom Johnson

      Sarah, thanks for sharing your experiences here. It sounds like you’re wrestling with exactly the same kind of situation I’m wrestling with in this post. I like what you say here: “How do we maintain coherency in a topic-based stand-alone or every page is page one approach without losing sight of the fact that a document containing many pieces is still a whole, and should be treated as such; even when single sourcing.” This gets to the heart of the matter.

      Overall, subject matters differ. Some lend themselves to more modular writing than others. For subjects that are more interconnected, it’s important to get the narrative flow right. For subjects that aren’t that connected, it’s not as high a priority.

      Regardless, I think this post and the comment thread surfaces a major concern about topic-based authoring that needs more exploration and strategy. The ultimate goal is to create a document that can be read as a whole or in parts and still make sense enough to users.

  • Craig

    Loved your post, as usual. Don’t know that I entirely agree, however. What I learned was, don’t bother with a clear narrative flow because users aren’t reading. They are, at best, skimming. Users are, more likely, hunting around for what they want and getting out fast. I’m all for a coherent narrative, but I would want to know, is this what users truly want and need?

    • http://idratherbewriting.com Tom Johnson

      Craig, no doubt many readers get in and get out fast. But what about the users who want to learn the system from the ground up? Help should accommodate that mode as well.

    • http://everypageispageone.com Mark Baker

      Craig, no doubt many readers want to get in an out fast. But for whatever minim of content that reader needs in order to get back to their task, they will get to their task faster if there is good narrative flow within that minim.

      That does present a conundrum of sorts, of course, because an excerpt from a book-length narrative flow does not always have good narrative flow itself when taken out of context. The larger narrative flow of the book may be assuming certain ideas or examples introduced earlier on which the current text depends: fine in the narrative flow of the book, but not fine in the narrative flow of the minim.

      On the other hand, a chunk of text sized to optimize for reuse is not necessarily (and, indeed, not likely to be) the whole of the minim that the reader needs, and so a pasting together of chunks, without narrative flow between and through them, is not going to work well for the reader either.

      This is why I think we have to start designing around a smaller unit of information delivery — the topic. A topic should have narrative flow. Such a topic is not an information chunk sized for reuse; it is an Every Page is Page One topic sized for use.

      This does not mean that every reader will read every topic end to end, but it does mean that the skimming reader, insofar as they need to orient themselves within the narrative flow of the information they alight on, will be able to do so within a reasonably short span.

    • http://idratherbewriting.com Tom Johnson

      Craig, thanks for commenting. I think users operate in different modes based on their information needs. In a search mode, as Jonatan puts it, users probably operate in a skim/hunt, get-in-get-out mode. But in a learning mode, where users want to understand the system from the beginning, I think they may look to print out a PDF.

      Here’s a related question. Why do we single source content at all, providing both online help and PDF, if no one reads the PDF? In that case, the print output is wasted. But I think we do acknowledge that some users are reading lengthier sections of the help to understand the material, not just reading one topic.

  • http://marciarieferjohnston.wordpress.com Marcia Riefer Johnston


    You’ve hit on a subject that has been underemphasized in discussions of topic-based writing: assembly–or, more to the point, the user’s experience of the topics after they are assembled.

    Kurt Ament’s seminal book, “Single Sourcing: Building Modular Documentation,” introduced me to the notion of topic-based writing. In this book, he uses topic-based writing to explain topic-based writing. His novel approach both fascinated and frustrated me. I was reading the book straight through–I wanted to learn. But the topics didn’t flow in a logical, cumulative way that would support learning. Beginners’ questions were not answered in the beginning; information chunks were repeated throughout the book in circular, unhelpful ways. Reading through those topics in order was a chore. I found the reading experience stimulating and edifying but also dizzying and unsatisfying.

    Ament’s book didn’t turn me off topic-based writing, but it convinced me that, ideally, topics work both separately AND together. Ideally, topics stand alone AND read well in sequence. Ideally, topics support random AND serial access.

    That ideal is apparently tough to reach.

    I’ve seen some examples, though, including the online Help for Adobe Acrobat 7.0 Professional. (I have no affiliation with Adobe.) Those Help topics supported users in jumping around between topics AND in scrolling from one topic to the next. And the scrolling sequence made sense.

    You won’t be surprised, Tom, that this sensible sequence followed your pattern:

    1 – Big Concept

    task, task, task…

    2 – Big Concept

    task, task, task…

    My first thought was, “Wow. Someone has put in extra effort to make these topics work for both kinds of reading,” that is, reading to do (random access) and reading to learn (sequential, cumulative).

    What does it take to create and assemble topics that support both kinds of reading? That’s the challenge. With help from blog posts like this one, and the conversation and experimentation that follow, more and more writers will rise to meet it.

    • http://idratherbewriting.com Tom Johnson

      ideally, topics work both separately AND together.

      I like your approach. I’m not sure why I assumed the two modes couldn’t be compatible. Just like responsive themes that display well on mobile and tablet and desktop browsers, why can’t content have the same flexibility based on the reading mode rather than the device? Thanks for challenging this assumption. Also, thanks for noting Kurt Ament’s book. That’s one book on my list of books to read.

      • http://marciarieferjohnston.wordpress.com Marcia Riefer Johnston

        Thanks, Tom, and you’re welcome. I’ll be watching for your review of Ament’s book.

  • http://marciarieferjohnston.wordpress.com Marcia Riefer Johnston

    I especially like your phrases “patience of a dead owl” and “a jumble of rusty parts forced into the same bag.” Thanks, too, for the pointers to Mark Baker’s posts. Good stuff.

  • http://lopascribes.wordpress.com Lopa

    Good post, Tom! I have pondered over topic based authoring for a while, and this post had some really interesting points!
    I believe help should be organized keeping in mind the following: a user while reading help always looks for ‘Why, am I doing this? What happened before I did this? What will happen if I do this? What should I do after I do this? How should I do this?’
    Irrespective of their category, novice or expert, all users seek answers for the above questions while reading a help material.
    If we pay attention to these questions, we will realize that they tell a story by themselves that falls into an implicit flow.
    Personally, I consider that writing help is nothing less than telling a story that contains number of stories within itself. When I write help, I don’t stick to any specific norm such as Topic Based Authoring. I first decide the overall organization and the connectivity between various topics, and only then actually write the content. Even while writing the content of individual topics, I deliberately keep track of the topic that is before the current topic, and also keep in mind of what will come next. I feel writing help is like solving a problem in maths, wherein while performing the steps we have to think of what the next step would be. It doesn’t matter whether the user looks for information haphazardly or sequentially; a writer should not write content haphazardly, and then mix them to bring out meaning.

    • http://idratherbewriting.com Tom Johnson

      Lopa, I like the questions you list there. I think answering those questions would certainly help give context and meaning to any task.

  • http://www.agiledocs.com Alok

    Good post, Tom. Topic-oriented architecture not only helps in classifying information types (concept, task, reference), but also helps in getting rid of most of the nice to have information in the user manuals. Minimalism coupled with topic-based authoring can go a long way in increasing the usability of the user documentation. Tools like IBM Information Architecture Workbench can come handy for creating the topic outline.

  • http://german-dating.org Gal

    Great article! I want to find more post about that. Any advice?

  • http://www.protechwriting.com/ Larry Czaplyski

    I’ve often thought topic-based authoring was an unhelpful way to present information. I recently posted a short article that touches somewhat on what you say above (Is Technical Writing Changing). I believe the basis of any type of writing, whether it’s a technical manual, an article, a non-fiction book, etc., is simply basic writing skills.

    It seems to me that many of the ways to present technical information (like topic-based authoring, information mapping, etc.) that are constantly bubbling to top of the technical writing zeitgeist, simply make the technical writing process more confusing. Traditional rhetoric has been around a long time and still has a place even in digital media.

    As for reading technical manuals, last night I was reading an early novel by Tess Gerritsen where one of the characters, an astronaut, enjoys reading technical spacecraft manuals when he’s not flying through space. I have to say, from there on, he didn’t seem a believable character

    • http://idratherbewriting.com Tom Johnson

      Larry, thanks for commenting and for linking to your post. This paragraph caught my attention:

      Rather we organize the material in a way that makes sense to us. A key benefit of this instinctual drive to organize is that it reveals defects in our coverage. We see where something doesn’t make sense or where additional information is necessary.

      Are you saying that we make too much of the topic of findability and organization? If we just organize content according to our own sense of logical groups, does that do enough? Maybe it does.

      I have grown a bit tired of my organizing content topic. I am turning more toward videos, since I think that users learn about ten times more quickly and thoroughly through the video medium.

  • Pingback: Topic size: Finding the narrative minim | Every Page is Page One()

  • http://www.protechwriting.com/ Larry Czaplyski

    No, I’m not saying that we make too much of findability and organization? Organizing writing in a way that helps users find what they need quickly is where a lot of the fun and challenge of technical writing comes into play. And this part of technical writing has nothing to do with technical but 100% to do with writing.

    I haven’t ever thought too much about topic-based authoring or mind mapping, but I think I’ll take a quick look to see what they are about. Why? Because I’m wondering if they are tools that make it easier for some folks to communicate who otherwise would have problems?