Topic-oriented authoring

Volume 10, Issue 7; 05 Feb 2007; last modified 08 Oct 2010

A visual analogy and the importance of good metrics.

I get asked about writing methodologies with some regularity. It often starts as a “DocBook vs. DITA” question, but it's not usually about the spelling of the names between the angle brackets. As I've said before, there's nothing about the DITA methodology that you can't do in DocBook.

Usually it's about topic-oriented writing vs. book-oriented (or what I'm going to call here “narrative”) writing. The subtext is often that the topic-oriented style is better than the narrative style. It'll come as a surprise to very few that I'm not convinced.

The narrative style has been around a long time:

  • It is built on “English 101” principles: introduction, successive exploration of new ideas, review, and reference.
  • “Knowledge units” (topics, sections, chapters) are supported by the units that preceded them.
  • Supports the reader by providing a context for the information presented.
  • Works in print and online.
  • Is not generally amenable to arbitrary reuse.

The topic-oriented style is relatively newer and has different features:

  • It is developed on principles of reuse and minimalism.
  • “Knowledge units” (topics) stand alone.
  • Focuses on documenting tasks, not tools, functions, applications, or systems.
  • Reportedly preferred by “learners” that tend to jump in and “resist detailed systems of instructional steps.”
  • Provides opportunities for the reader to explore in arbitrary directions.
  • Works online; may work in print.
  • Offers the opportunity of arbitrary reuse.

Recently, I was describing to a group of documentation managers, tool writers, and authors how I think these two styles differ and what appear to be their respective strengths and weaknesses. In the course of this discussion, the following analogy occurred to me.

Imagine that instead of authors, we were painters. In the narrative style, a painter (or perhaps a group of painters) begins at one side of the canvas and paints it from beginning to end (from left-to-right and top-to-bottom). They may not paint it in a strictly linear fashion, but the whole canvas (the narrative whole) is always clearly in view.

The result may be a little ragged around the edges, and there's no gaurantee that there won't be voids on the canvas, but by and large the result is a complete pictureIn this case, Starry Night by Vincent Van Gogh.:

Starry Night by Vicent Van Gogh

In the topic-oriented style, the work is divided into topics, or by analogy, the canvas is divided into squares. For this painting, perhaps we'll decide that 60 topics will cover it.

Each square, or topic, is painted in relative isolation. To the extent that the author has the whole topic in view, it too is likely to be relatively complete.

A single square of the painting

In addition to creating individual topics, to save time and effort, similar topics from other paintings can be reused. The final work is achieved by mapping all the topics into a whole:

A checkerboard version of Starry Night by Vincent Van Gogh

Of course, there's nothing that prevents the authors from filling in each topic right to the edges. Nor is there any reason why the result has to have holes in it. But I bet most of you have had an experience similar to this one:

The printer in Deb’s office started to jam. This being a modern piece of hardware, it didn't ship with a printed manual. It didn't even ship with a PDF file of a printed manual. No, instead it shipped with a large topic-oriented help file, er, manual.

After a half-hour or so of searching and following links, I concluded that the manual contained six or seven topics related in one way or another to paper jams. Each of them was two or three sentences long. Each linked to two or more of the others. And none of them actually contained anything very helpful.

So, if the author's metric for success on the question “do we have paper jams covered?” was “Yes, we have seven topics about them,” then I think the metric was a terrible failure.

Similarly, if the author's manager's metric for success on the question “did we produce better documentation faster and cheaper?” was “Yes, we reused seven topics about paper jams without any new writing,” then I think that metric was a terrible failure; not because it wasn't faster and cheaper, but because the resulting documentation was a nearly worthless stack of…bits.

It would be ridiculous for me to suggest that it's impossible to write good topic-oriented documentation, but I think it's a lot harder than it looks. Likewise, it would be narrow-minded of me to suggest that there aren't subjects that lend themselves to a topic-oriented treatment such that the narrative style would be more difficult and expensive to produce.

At the end of the day, I think the really important question is, did the documetation you produced, regardless of the style chosen, actually provide clear, concise, and accurate information for your readers? Your readers probably don't care how many pages you wrote, or how many topics, or how much faster you wrote it, they only care if it answered their questions.


The on problem with topic based writing I have noticed is reuse can often times be more difficult than just rewriting the content. This could partly be because of a lack of well written topics, but I do wonder if writers are better off with tools that facilitate reuse without forcing a writing style. For example, using a topic based library for searching and using snippets, yet creating new content from scratch. There are obvious issues with this as well, but if your library is essentially something like indexed FrameMaker files and you use by-reference includes, it can be a very efficient system that doesn't reduce readability. With that said, it is obviously different for everyone's situation.

—Posted by Eric on 06 Feb 2007 @ 12:06 UTC #

A better picture for illustrating topic-oriented writing might be one of David Hockney's portraits made from dozens of polaroids. Each photo is fine in itself, but they inevitably all have slightly skewed perspectives and bits of redundant overlap that makes for an interesting multifaceted portrait that also shows how you can't get the effect of a continuous picture (narrative) by assembling context-free fragments.

—Posted by Damian Cugley on 06 Feb 2007 @ 02:45 UTC #

"at the end of the day". Ugh.

Sorry, pet peeve of mine.

—Posted by Jeff Atwood on 06 Feb 2007 @ 07:40 UTC #

Uhm. Your peeve is what, exactly? You just don't like the phrase?

—Posted by Norman Walsh on 06 Feb 2007 @ 07:43 UTC #

See my blog entry on this at Palimpsest

—Posted by Sarah O'Keefe on 07 Feb 2007 @ 02:40 UTC #

Interesting post Norm...

The DITA community seems to be in the same place that the public-sector educational technology community was 6 or 7 years ago, with respect to so-called 'learning objects'.

The lego-block metaphor of reusability without revision, in all contexts, was very seductive for administrators and funding bodies, who envisioned academics happily pulling learning objects out of repositories and aggregating them into courses, with no rewriting or editing required.

This was an absurd promise to make, as most academics make liberal use of narrative style in their content, and the results of aggregation were often an incoherent mess.

DITA certainly works well for certain types of tech-writing, and I'm applying it to training materials in my own workplace, but the notions of topic-orientation and reusability have been heavily over-marketed, indeed they've been elevated to the status of dogmas. And this emphasis shifts focus away from some of DITA's other strengths: e.g. rapid specialization of content models, rapid configuration of editing tools, and rapid development of publishing outputs.

—Posted by Doug Burgess on 14 Feb 2007 @ 07:57 UTC #

I used DITA at IBM for a while. Not long enough to claim power user status, by any stretch. But enough to get frustrated that I was spending more time managing little pieces of information than writing them. In fairness, I should mention that we were also using a high-end content management system with DITA. Anyway, it was a revelation, because I had drunk the sgml/xml kool-aid about reuse and was enthused to learn about DITA.

My current opinion is that some amount of reuse is undoubtedly a good thing, but snatching a lot of little snippets out of the ether and assembling them into topics makes more sense for web catalogs and airplane assembly manuals than for readers who are trying to learn or understand complex systems. I like Norm's use of the term "narrative" to describe what can get lost in the shuffle when reuse becomes an end in itself.

—Posted by denisb on 10 Apr 2007 @ 02:12 UTC #

Definitions, please. When you say Topics-- Do you mean feature-centric documentation? That's horrible stuff. The real challenge is to figure out what the end-user expects to do with the product...that requires you to have some domain knowledge beyond the product you are documenting.

For example: that printer. People will want to print from their pc, make copies of printed documents, use different paper sizes and types, interrupt or cancel a print run, etc. A good table of contents (navigation) lets the user ignore the background noise created by a linear narrative. However, "topics" that have names like: the paper cartridge, the document feeder, the collater bin, etc. are just as noisy.

I think links that force you to jump around are user-hostile. Just put it all in one logical place with collapsing/expanding subtitles. I think most people would rather scroll than jump when they need help - they don't want to lose their place while they're searching...

—Posted by JP on 06 Jun 2007 @ 10:35 UTC #

Your example of dividing the canvas into squares is not very realistic, which of course helps you prove some point better.

I would change the story like this:

The aim is to have a "live" painting of our town on a pub wall. We have the pub owner, a painter himself, and some of his painter friends.

The owner is good at composition, one friend is obsessed with the sky, another has painted a lot of houses and streetscapes, the third likes trees and hills.

So the owner draws some outlines on the canvas: Here we will have houses and a church. To the right there will be a hillside with some woods. Up there the sky with the moon and stars. The canvas might then even be cut in pieces, not squares, but along the lines of the composition. Zippers are attached to the cut edges. The friends get to work and fill out their pieces.

Then they gather again for a beer (or more) and try to fit the pieces together. They all see where they need to do some refinements, as they are all painters, but the owner, both becasue he is the owner after all and because he is best at composition, gets to accept and zip back together the pieces.

In the winter the woods shed the leaves and go greyish brown instead of the summer green. So it is time to unzip the part with the hillside and change the coloring. Then it is zipped back to where it belongs.

A few years later the church gets struck and burnt to ashes by lightning. So it is time to unzip the part with the houses and paint the houses behind the church to where the church itself used to stand. Then it is zipped back to bere it belongs. But wait! says the owner, the church tower covered part of the hillside, so now we have a hole there... so need to adjust another piece as well to keep them fitting together.

End of the story? well no, the story keeps going on and on forever, at least until the pub owner dies.

So I would say it is possible to create good topic oriented writing, if you have a good editor and good writers, who all take their time to also read the chapters of others and have the full picture in mind while working on their own chapters.

—Posted by Marton Kadar on 14 Oct 2009 @ 12:51 UTC #

Comments on this posting are closed. Thank you, spammers.