- The Tyranny of the Terrible Troika: Rethinking Concept, Task, and Reference
- A Reference is Not a Topic
- A Task is Not a Procedure
- Everything Else is not a Concept
- We Must Develop Topic-Based Information Design
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.
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?
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.