October 18, 2007
It's the design, not the documentation
There's a good discussion going on the Framers mailing list today, with this post by "tekwrytr@hotmail.com" being of particular interest:
Technical writing, specifically end-user documentation of software applications, is perceived by the majority of producers as "less than useful" and, in general, a waste of money, time, and effort. Similarly, the TW's view that they are "adding value" to a product may be just as impoverished.
Documentation is not used by the end-user because it is awkward, poorly organized, and in many cases, indecipherable for a user seeking task-accomplishment assistance. Linux is a primary example; despite some of the most dedicated, motivated developers on the planet, and droves of TWs spending endless amounts of time creating "tutorials," introductions," and "documentation," (along with a massive PR pitch by IBM a few years back), Linux languishes. Users avoid it because it is "too difficult to learn."
The underlying cause begs exploration, and is at the heart of technical documentation; does the TW really want the witless user to understand what the TW finds conceptually difficult? Or is there the same tendency in TW that is found in academia — "I took years to learn this, and you expect me to tell you how to do it in half-an-hour?"
I am not suggesting for a minute that the process is planned, or even that the TW is aware of it. I am suggesting that the underlying premise of technical documentation is not "documentation" (as in "creating a record of"), but knowledge transfer. It is in the area of knowledge transfer that TW comes up short. Of all the software documentation available on October 18, 2007, how many pieces are considered easy-to-use by users?
What I suggest is not a simplistic condemnation of TW, or TWs. What I suggest is that the underlying premises of TW may be impoverished, and suffer the same weakness as academic "instruction." That is, replaying the one-to-many lecture style of Aristotle on the computer screen, in the mistaken belief that a user really cares whether every i is dotted and every t crossed, or that a consistent style is used for all code samples, and a consistent voice is used for all explanations.
Finally, the reason that user interfaces in software applications require extensive documentation is a failure in the design and programming stage, not in the documentation stage. If the interface were competently designed, it should be "intuitive" to use, and require only minimalist documentation. If there is a future for TW, it lies in the area of facilitating knowledge transfer, rather than an obsession with style, form, and consistency.
Reproduced by permission.
Posted by Nicholas at October 18, 2007 12:39 PM
As a snooty technical writer myself, I have a few issues with this post.
The author states, "If there is a future for TW, it lies in the area of facilitating knowledge transfer, rather than an obsession with style, form, and consistency."
That's a no-brainer. I think we can all agree that the quality of instructional content is far more critical than the style, form and consistency of the writing itself. I don’t think any technical writer would argue otherwise. Although many technical writers serve as their own editors, the processes of writing and editing are distinct. Although it is good to keep style, form and consistency in mind while writing, they are all things to double check during the editing process. The goal of technical writing is to clearly communicate technical information to a (typically) non-technical audience. The only way to achieve that goal is through quality instructional content. Duh!
Also, I think we can agree that as long as humanity creates inherently unintuitive things (from software to garage door openers) there will always be need for clear, concise operating instructions, and thus a need for technical writers. Implying that the future for technical writing is somehow threatened, outdated, or unnecessary is alarmist and absurd.
The author states, “Documentation is not used by the end-user because it is awkward, poorly organized, and in many cases, indecipherable for a user seeking task-accomplishment assistance.”
Then why do any of us continue to be paid for our services? If the work product was always horrendous, why is there still a need for it? I have seen many examples of quality end-user documentation.
I do agree that users are primarily interested in task-accomplishment assistance. Users don’t want to read an entire manual to figure out how to perform a task at hand. If the manual has a table of contents and an index, guess what, they typically don’t have to read every word of the manual. They can use an inventive device called a page number and look up the precise page of instruction relating to their task. Task level assistance can also be achieved using interactive tool tips, context sensitive help files, and in some cases simply writing out pointers on the application itself (many Web-based applications provide instruction right on the application’s page). If a client isn’t willing to budget for this level of assistance or for quality documentation, it’s the client’s fault, not the technical writer’s.
I agree that every effort should be made to facilitate user instruction; but at some point users must stop whining and read the instructions. Yes, no-one likes to read instructions. Most of us like to jump right in and start using the application or product. But after we’ve broken the product or get stuck using the application we eventually have to break out the instruction manual to understand how to accomplish our task.
One last note. Implying that Linux is not a widely used operating system because its documentation is confusing is an extreme oversimplification. What about the fact that Windows comes pre-installed on most PCs? What about the fact that Windows is the standard operating system for most businesses? What about the fact that Windows has a consistent and reasonably easy to understand GUI? What about the fact that Windows ships their OS with a large driver pack? What about the fact that there is a standard process for installing and uninstalling applications under Windows? What about the fact that, for typical users, maybe, just maybe, it IS easier to use Windows than Linux? Linux is languishing because of poor documentation? Come on.
Also, why abbreviate "technical writing" throughout this post? Is it that much of a burden to type out?
TWs ftw!
