Hidden Factors of Documentation Quality -- Part 1

The first impulse of many documenters is to turn our work over to editors and graphic designers, or to form committees and develop style guidelines. All of these measures are useful, but none can assure us of quality when there are basic problems with the way we go about producing documentation.

Sesnovich, Bruce A. Boston Broadside (1993). Articles>Documentation>Quality>Technical Writing

Robert Pirsig’s Message for Documentation Quality  

Teachers of technical communication frequently recommend that their students read Robert Pirsig's Zen and the Art of Motorcycle Maintenance (1974) for his views on the complex relationships between technology and human values. As a former technical writer, Pirsig also offers some useful advice about Quality and its relation to the usability of technical documentation. Revisiting Pirsig’s works, including the more recently published Lila (1991), reveals concepts about Quality in documentation that are especially relevant to the usability testing of the documentation for today’s rapidly evolving technologies. This paper examines Pirsig’s views on the some of the characteristics of effective technical communication, and it offers advice to educators and trainers for incorporating Pirsig’s concepts about Quality into their teaching of techniques for the usability testing, and hence quality, of user documentation.

Shirk, Henrietta Nickels and Howard T. Smith. STC Proceedings (1998). Articles>Documentation>Quality>Technical Writing

“Good Enough” Really Isn’t

I’m enough of a perfectionist that I mentally wince every time I find myself thinking, “It’s good enough.” It sounds like a cop-out. It sounds like avoidance of responsibility and ownership. It sounds like I’m indifferent.

Gryphon Mountain (2009). Articles>Documentation>Quality>Technical Writing

Case Study: Communication Problem vs. Programming Problem

In looking at my documentation, I found a couple of inaccuracies, and it’s possible that they were the direct cause of the data problem we ended up with. I haven’t verified this yet because at this point, it looks like it hardly matters (as long as I correct the inaccuracies). If my documentation led to the problem, it has led us to analyze a bigger problem that’s really at the heart of our customer’s difficulty. The discussion has been about what needs to happen in our system vs. what is actually happening. We think the programming and the data model have fallen short in some ways; fortunately, the wiring can probably be fixed with relatively little pain. It’s a matter of making sure we know what the customer wants to happen so it will be programmed the right way.

Minson, Benjamin. Gryphon Mountain (2010). Articles>Documentation>Quality>Technical Writing