Topic-oriented architecture

Norm has a post describing his explorations with the features that make DITA (the Darwin Information Typing Architecture) unique. I haven’t really been following DITA, other than to note the fairly high-powered participants, including both users and implementors, in the OASIS TC and to assume that it was driven by some of the same goals as the old IBMIDDoc documentation system, which I’d guess is still in use. (Hey, Sun’s on the group!) (Uh, guys, could you include direct links to the specs for convenience rather than requiring me to download a zip file? [UPDATE: Thanks to Mary for providing direct HTML links in the comments.]) (I’m getting a strong whiff of that IBMIDDoc “look” off the specs.)

Going into writing this post, I guess I had a bit of the same impulse towards DocBook protectiveness that Norm had. But I very much respect the goal of designing a system that is meant to have reusable parts, rather than trying, as many have done over the years, to reuse what I think are inherently non-reusable documentation structures.

Let me explain. In my years in DEC’s documentation groups, we had endless committees trying to define what “modular documentation” is, how to achieve it, etc. I spent quite a lot of time in the early days of the OSF DTD design project (a bit of information on it can be found in this DocBook history; I should dig up and re-digitize some of my old design docs from those days) arguing that it’s pointless to have nestable Section elements if what you want is modularity. Unless you have unbelievably strong editorial guidelines and whip-crackers, you can’t assume that any one Section instance will have been written in such a way as to support plucking it out of its original context and reusing it. Imagine, for example, that you’ve used a top-level Section element to create a “chapter” of what will be your printed documentation. You may have included introductory text in it that says something like “This chapter discusses…”, and the scope of the section is likely to be extremely broad — not suitable for immediate demotion to a sub-sub-sub-section.

At the time, mostly what you got from nestable Sections was the easy ability to promote and demote information in the Table of Contents as you write and revise — which was perhaps important in an era where authoring tools didn’t help you do this very effectively. But this wasn’t the same as achieving modularity! I used to joke that the best way to achieve modularity was to pay technical writers per-use royalties on modules that actually got used by other writers.

Part of my intransigence in the OSF DTD group discussions came from the fact that, around the middle of my technical documentation career, I had moved from the Digital VMS Layered Products documentation group to the ULTRIX documentation group — and discovered man pages. Why, here was the perfect example of modular documentation, and it had been there all along! This, I believed, was the way to define reusable structures. To me, the requirements were:

• A c