Like the link bait title? Well stay and enjoy the post....
I find topic-based writing evangelists to be an annoying scourge to the technical writing profession. That is not to say that I am a narrative apologist. I just find the narrative crowd to be more reasonable than the topic crowd. Maybe it is that the narrative crowd has accepted their defeat and the the topic crowd are still fighting the war. I think is that the narrative crowd know that on the fundamentals they are right and are willing to adopt new thinking to improve the profession while the topi crowd knows that on the fundamentals they are weak and cannot tolerate challenges to the dogma.
I fall somewhere in the middle of the two crowds. I believe that the narrative crowd knows what it takes to make technical documentation that is useful for all ranges of users. Knowledge transmission depends on context and order. Many things need to be done in a set order. Knowledge builds on prior knowledge. The larger organizational structures-books, sets, help systems, libraries-we use to present that information need to reflect these truths. In a lot of cases the building blocks must also bend to these truths and provide hints to the larger structure. It also true that there will be some amount of bridging, or glue, content that will need to created to provide context and flow through the material.
I also think that the idea of breaking technical documentation into atomic chunks that can be reused and distributed to a number of writers is a good practice. There is no reason that a section in a book cannot be written as a standalone piece of content that is eligible for reuse where appropriate. In the case of online help, each of the pages in the help should be as independent as possible. Even in books that are presented in HTML should have pages that can intelligibly standalone. In these cases, there is a high probability that the pages will be viewed out of order and without the supporting context.
I think the strengths of narrative and topic can be, and have been, merged into successful systems. I like to call it modular writing and it is not an original idea. It doesn't require any fancy tools or even a special writing tag set like DITA or DocBook. All it takes is a little discipline and agreed to conventions. To make it work, you simply agree to what constitutes a content module. For example, the team I work with uses the section element. You also agree to some basic ground rules for the boundaries of a content module. We have a loose definition that a module is the smallest set of content that can usefully standalone. This does not mean that it is just a concept or a task. In a lot of cases, what the topic crowd deems a concept or a task does not constitute a set of information that can usefully standalone because a free floating task may require some context to make it useful instead of just simply a set of steps a monkey can perform.
Unlike topic-based system which disdains bridge content, leaves space for bridge content which can, if it makes sense, be included in a module, or it can be put in a separate module. Our system allows it to be placed in the map outside the scope of any module. We use DocBook, so bridge material can be placed in a chapter before any sections or in a section before any sub-sections.
So where topic evangelists proclaim that bridge content is wasteful and that context is a quaint idea clung to by dinosaurs, I proclaim that they have a very useful place in writing. I also proclaim that they are not always required or even desirous. These things are important tools to help guide novices and provide background for experienced users. They aren't useful to a ninja user who just needs a refresher on navigating a UI or remembering the syntax for an API.
Ditching them impoverishes the overall content and makes the content little more than a collection of tiny factlets that are strung together by a gossamer strand. It means that you can hire a bunch of low skill writers to gather the factlets and beat them into the required form while some "information architect" assembles the pieces into what at first glance looks like a sufficient documentation set. It is the assembly line model. Unfortunately assembly line documentation often results in things like your typical auto manual or coffee maker instructions.
Everything you've said against assembly line methodologies is valid, but it equally applies to anything. A craftsman can make a single piece of furniture themselves as one job, ensuring that all the joins are seamlessly, the wood matches and the design is according to the customer's precise specifications. But instead, everyone buys mass-produced flat-pack furniture from Ikea. Why? Because it's cheaper. Ikea is a fantastically wealthy trans-national corporation, but I've never met a bespoke furniture maker once in my life. Manual professions have now almost entirely been taken over by industrial assembly line processes. It is naive to think that knowledge worker professions won't be next. If you're not building a robot to take over your job, you're on the losing side of the march of progress.
ReplyDeleteWork is already underway to do this for writing. These CMU researchers are running an interesting project:
http://mybossisarobot.com/
Just because the current trend is a race to the bottom doesn't mean that standing up for quality is being on the losing side. At some point people will begin realizing that they would rather pay for something that works properly rather pay for a lot of crap that is mostly good enough.
ReplyDeleteOne more point is that there is a difference between furniture and technical documentation. Ikea and GM and Apple or any other company that make products for the masses. Technical documentation is much closer to bespoke furniture because it is tailored to a single product line. In other words it is a single use case product. It is also something that it built once and replicated through the magic of digital copying. Mass produced products serve a number of uses and require multiple physical builds of the product. I can deliver a million copies of a book from a single file, but I must build a million copies of a chair before I can deliver them.
ReplyDeleteAlso, I am not entirely dissing all of the efficiency enhancing techniques that automation can bring along. In fact, I love automated build systems with built in link checking. Modularity can also be used to make it possible to write once and use multiple times. None of these things are anti-quality per se.
ReplyDeleteMy argument is that the current topic craze defines things to narrowly and too rigidly to be very helpful.
I also like to caution that any attempt to become more efficient by jumping on the current bandwagon is unlikely to make a team more efficient or their documentation any better. Generally all it does is result in more of the same with some slightly different problems. Good teams with a clear vision and a dedication to quality know how to make good things efficiently.