We Must Develop Topic-Based Information Design

By | 2012/08/27

There is a lot of talk in tech comm today about topic-based writing, but very little about topic-based information design. This is a problem, because, in the age of the Web, and particularly of the mobile Web, topic-based information design is essential.

Topic-based writing is often perceived (and practiced) as nothing more than writing in small, potentially reusable, chunks. As such, it says nothing about what kind of information design those chunks will be assembled to create. Often, such topics are assembled to create books, or, sadly, the monstrosities I have dubbed Frankenbooks.  Seldom are they used to create something that a reader would encounter as a usable topic — that is, a sufficient treatment of a single subject of interest.

Unfortunately, due to the default publishing mode of DITA and most DITA tools, the reader often encounters the reusable chunks of current topic-based writing practice as separate pages in a Frankenbook manual. In an excellent blog post Case study:  DITA topic architecture, Ruth Haworth describes the all too common result:

 I started with DITA several years ago when I got a job in a large doc team that had been using DITA for a while. I inherited a few deliverables and was appalled at the way the content was broken up into concept, task and code sample topics. We optimized for HTML output and there were too many brief HTML pages that users had to click through. Even for a simple idea that could have been covered in one paragraph, these docs would have three topics. For example, a description of how to stop the server would have a concept, task and sample topic, each appearing on separate HTML pages.

My audience was developers. I did quite a lot of usability testing with them and found they were furious about the documentation. They hated having to click through multiple tiny pages. They hated the minimalism and choppiness. They described the docs as unfriendly, officious, insulting and unhelpful.

Man assembling jigsaw

Topic-based writing is about assembling content out of pieces. Unfortunately, the reader is often presented only one piece at a time, which does not work well for the reader. (Free image courtesy of FreeDigitalPhotos.net.)

The basic problem is, the chunks into which content typically gets divided in “topic-based-writing,” whether in DITA or not, are simply too small to work independently for the reader. Reusable chunk topics are sometimes described as being able to stand alone, but, as I discussed in What is a Topic? What does Standalone Mean?, the ability to stand alone grammatically is not the same thing as the ability to work alone for the reader.

To create topics that work alone for the reader — Every Page is Page One topics — we need to focus not merely on topic-based writing, but topic based information design.

But why topic-based information design at all? That is, why produce content to be read as topics rather than to be read as books? Couldn’t we just write off topic-based writing as an experiment in how to write books that went horribly wrong and created Frankenbooks? Isn’t the solution to that to go back to writing books properly so that they work as books?


Topic-based information design is like the painting of miniatures. A topic is complete and usable in its own right. (Image is a miniature of Margaret Roper by Hans Holbein the Younger, from Wikimedia Commons.)

No, that’s not the answer, because, quite unrelated to the attempt to make book production more efficient by writing in chunks (I gave a paper on Component Based Information Development back at SGML 95) the Web has transformed the way people consume information. The Web is a medium of topics, not a medium of books, and people want most of their information today, whether delivered on the web or not, in topic sized chunks.

I spent as many years as anyone working on techniques for creating books from reusable chunks (thus the SGML 95 paper), but frankly, that work is more or less moot today. Today the principal challenge before us is to create Every Page is Page One topics for the Web generation.

Whether such topics can or should be created from reuseable chunks of content is a separate and secondary issue. If we can take anything from the experience of the attempt to build books out of components, it is that we must at all costs avoid any system that leads to the creation of Frankentopics. The terrible troika of task, concept, and reference belong to the world of topic-based writing, not to the world of topic-based information design.

But the key challenge before us, as the irresistible gravity of the Web draws tech comm, however reluctantly, out of the book-based paradigm of technical communication, is not topic-based writing, but the development of a robust theory and practice of topic-based information design.


Series Navigation << Everything Else is not a Concept

7 thoughts on “We Must Develop Topic-Based Information Design

  1. Pingback: Are you focused on delivering information or chunks? « 50 States Project

  2. Debbie M.

    On “the development of a robust theory and practice of topic-based information design…”

    Any thoughts? Ground rules?

    1. Mark Baker Post author

      Thanks for the comment, Debbie.

      Thoughts? Ground rules? — A few. Every Page is Page One, to begin with. And I think we need to grapple once more with the old question of how big is a topic — that’s the post I am working on now.

  3. Pamela

    Hi Mark,
    An excellent article. I find myself immersed in writing topics at my new job. The goal – usable “articles” for the field engineers on the front lines doing PoCs for our potential customers. I use a wiki and I love the immediacy of the tool. I troll field engineering email threads and extract nuggets of information. I write up the topic, add a page to the wiki (not worrying about TOC and exactly where to place it), tag it with a few tags and save – voila, it is available for consumption. This project is a new initiative to enable our field engineers and feed them relevant info on topics they encounter on the front lines. If the information warrants, some day it might get folded into the product documentation (also done on a wiki). This is topic based writing at the edge, I think.

    1. Mark Baker Post author

      Hi Pamela, thanks for the comment.

      Yes, I think wikis are a great incubator for ideas in topic-based information design.

  4. Myron Porter

    As always, thoughtful and thought-provoking.
    Advanced apologies for over-simplification, but what about the Oxford English Dictionary? By adding historical examples of usage, it is to some degree a topical information model. By extension, English usage manuals such as Fowler’s or Garner’s are as well–perhaps more so.

    Anyway, I am not proposing using dictionaries or usage manual as the model for topic-based information design as much I am attempting to get at the basic building block for the design. This was provoked to some degree by the article on glossaries: http://idratherbewriting.com/2012/08/09/why-glossaries-help-users-find-information/

    Again, thanks your efforts and for providing a format for people like me to benefit and brainstorm a bit.

    1. Mark Baker Post author

      Thanks for the comment, Myron.

      You raise and interesting question. My first thought is to say that the OED and Fowler are not topics because references are not topics, they are databases (/2012/08/14/a-reference-is-not-a-topic/).

      But your point about the rich background information that references like the OED include make it a fair question whether a reference entry can include a topic. Including a topic is not the same thing as being a topic, of course, but it does raise an interesting question about reference information design.

      One caveat I would make about the idea of a reference entry containing a topic is that a reference should be first and foremost fielded data — a reference is a database, and its content should be accessible to queries to the greatest extent possible. So I would never advocate making a topic-oriented presentation of information that could be modeled as fielded data.

      Nevertheless, for B2B tech writing at least, I am strongly of the opinion that a rich reference set is the foundation of a tech comm strategy, so reference entries that include topics is certainly a possibility to consider.


Leave a Reply