http://norman.walsh.name/2007/02/05/painting 10 7 2007-02-05T10:24:38-05:00 $Date: 2007-02-05 13:33:58 -0500 (Mon, 05 Feb 2007) $ Norman Walsh 2007 Norman Walsh 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 picture In 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 Walsh ’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.