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.

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.

"at the end of the day". Ugh.

Sorry, pet peeve of mine.

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

See my blog entry on this at Palimpsest

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.

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.

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...

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.