Real Problems for Documentation Writers

I am a budding user interface designer and my biggest hurdle creating documentation (with companies I have worked for) is technical people. Scott's recent article's question: "Do you usually task your developers with creating documentation, or do you bring in technical writers?" is the wrong question. Now understand, I read Scott's articles, and appreciate his insight very much, and usually agree with his answers to the many vagaries of corporate IT problems. So what follows are the observations of a friend, and loyal reader.

To cast this part of the the question in this way ("Do you usually task your developers with creating documentation, or do you bring in technical writers?") reveals the entire problem with typically poor software documentation, and also, with poor interface designs. The problem with the question is that it assumes two different kinds of technical people: either the answer should be that technical developers will write the documentation or that technical writers will. The common problem with both statements is the word "technical." Scott is essentially asking "Which of the two techies will solve the problem for you?" The problem is that technical people cannot solve an instructional writing problem. One would expect that technical writers have the skills to solve this problem (after all, they are "writers," right?), but they most often cannot do so, for two reasons.

1) Technical writers are usually techy-types first, writers second. Personnel departments hire them not on their abilities to teach or write well, but as technical people first and foremost. 2) Technical writers usually think of their writing abilities as secondary attributes--the really neat stuff of their jobs is figuring out all the good (technical) stuff. In fact, I would say most of them think of their abilities to understand technology as the primary goal of their job and personal interests. Writing abilities are made subservient to this primary goal. Thus, technical writers can readily understand the workings of software, but rarely understand the workings of an interface design on the non-technical human mind.

This is important--technical writers are really describing (writing about) interface connections: either the user interface or a lower-level interface (such as function calls within a piece of program code or machine language communication between software and hardware). But the problem is that technical writers are not trained either to teach or describe difficult ideas to the non-technical human mind--they have instead been trained in mathematics and other technical subjects: mostly to solve problems, not teach. It is like hiring a well-spoken (and well-credentialed) car mechanic to teach driving. Bad idea! O.K., so I may learn about the four cycles of a typical car engine (Intake, Compression, Power and Exhaust): but I don't try to be aware of where the pistons are in these cycles while the engine is running in order to be a better driver. In fact, though I do know much about the inner workings of an engine (I grew up in the Detroit area), I rarely (if ever) think about them while driving. My destination, and comfort-level driving the car are uppermost in my mind--as well as spotting and avoiding the occasional bad driver in order to avoid a wreck.

The real problem here is that technical people, developers and technical writers, are not usually concerned with the "destination," but the inner workings of the "machine" being developed. However, the users of the software are interested primarily in the destination (what they want to use the software for), and not the inner workings of the software machine that is being designed to "get them where they want to go--as quickly and comfortably as possible." Essentially, non-technical people want the machine to virtually disappear into the activities of their daily tasks, while technical people want to showcase the machine and ignore, as much as possible, the daily tasks that machine is supposed to perform. It takes a different kind of person than either a developer or a technical writer to solve these issues.

It takes someone who can learn complex ideas and translate them into language easy enough for almost anyone to understand. It doesn't take teachers, for teachers have been taught to emphasize, not the basics of a given subject, but the techniques of teaching. The word "technique" here is just another word for emphasizing the technical. But for pragmatic reasons, companies sometimes hire teachers, or people who have teaching degrees, to help with documentation. This oftentimes has the same result as hiring technical writers: teachers who love teaching often love the mechanics of teaching more than the subject matter they teach. That was the problem with the bad Math, Science or English teacher we have all occasionally had. They may have known their subjects very well, but they loved the teaching part of their job more than seeing their students grasp the fun intricacies of the subject at hand. All our really great teachers accomplished both.

What is needed (and I have never found a company who yet does this) is a creative person. That's right--a creative writer. Although Scott also said "many application development managers attempt to improve the quality of their software documentation by employing technical writers or business analysts. This presents the opposite problem: Technical writers and business analysts usually have limited technical skills." This is rarely true of Technical writers, but it is true of writers who attempt technical documentation. These people are really writers first--yet another type of techy: one who enjoys, more than most things, the mechanics of writing. But what Scott really meant was not technical people, but this kind of writer--one who really understands the practice of writing better than technical subject matter.

I am a creative writer who was forced into learning computer technology in the mid 1980s in various jobs I had. Over the years, I became an instructor and support technician. I finally realized, a few years ago, from all this experience, that the main problems people have with computers are twofold: the interfaces are difficult to understand (they are often too technical) and they are often unstable (buggy). Good documentation does not solve either problem: good user and low-level interface design does. The problem posed in Scott's article: "What Makes Software Documentation Good" misses the point. If the design of the interfaces are good, the documentation will be easy to make. But in order to see what is possible, one has to use a person who is expert in seeing the possible and creating it. I found I had a lot of computer responsibilities dumped on me because of my lack of seniority, and I used my creativity to adapt to this situation. I learned the inner-workings of computer software and hardware well and then used my (creative) writing and teaching skills to create easy to use documentation, in words and with metaphors that non-technical people could understand. I became, as all artists can, technical, but without losing sight of my creativity, or the necessity to use my creative writing skills as a means of teaching the software to others.

It's like this--most of us have worked to develop relational databases in our careers. We created tables, wrote programs for calculating, sorting and reporting, etc. then built an interface. Do you remember the first time you realized that you had to recreate user interface, because it wasn't working as well as you had imagined it? Do you remember this leading to your redesigning the table structure? I do! After four of five times doing this, I started to begin all projects with the user interface. Once I got that design down on paper, it helped to create better (and therefore, faster and more stable) database tables, which resulted in more stable programs. The user interface, if intuitive (and therefore, efficient for the user), gave me all kinds of hints for how to design the architecture of the database--things I had often missed before in typical "missing the forest for the trees" fashion.

The problem with needing documentation is really that there is a significant problem with the interface--either for the end-user or an intermediary developer or programmer--or other technician trying to solve some problem. The real issue here is one of design--a subject all artists understand and use well, but which technical people, as a rule, do not. Technical people understand how to do things well, creative people understand how to make things well--and useable. The proof in the pudding is Games. Games are often just as complicated and system-intensive as real-life programs, and often have substantial documentation. The difference is that it takes users seconds to minutes to figure out how to make games work, but hours to figure out a new database program. In games, the user-interface is intuitive and the low-level interfaces are object-oriented and streamlined. And the marketing of games is more competitive than real-life programs too: game makers are obligated to meet rigid and fast-paced development deadlines and keep the cost of their products in reach of most adolescents or their middle-class parents. Finally, the documentation that comes with games is being reduced in size every year--because the interfaces are becomming intuitive.

But the best proof of my argument that comes from games is that I can easily figure out what to do so well, so quickly and so enjoyably, that when I play most games, I am unaware of the computer or the game's user interface--I simply play. The same thing goes for real-life programs I intuitively use. I focus on the work, not the machine or the software. If I can forget about these two things operating in the background, there is little need of documentation.

But if I need to have documentation, then creating an intuitive user interface, based on the user's mental task-model, will provided the best stepping-stone to making the documentation--just as beginning with the user interface makes it easier to create stable program code and relational tables. Unfortunately, adding creative people to design teams seems too risky for Personnel departments. But oh, what profits cold be made if they were!

If you doubt my claims here, I can put my money where my mouth is. I would be willing to send you a before-and-after interface design I created that shows the pathetic module redesigned into an intuitive, user-based, task oriented interface. The design was for a veterinary practice software firm: I redesigned a two-dialog animal boarding module interface (with no easy return to the main dialog, and several difficult sub-dialogs) into an easy-to-understand and use single dialog with four tabs. Just tell me what your limits are regarding attachment file size and I will be glad to show it to you. Remember, all this came from a guy who never took a computer science course during his college years, but who was extremely creative (as a writer among other things). I submit that if you all begin to hire creative people like me, we would make you more money in your companies than you could wildly dream.

But you would have to get around your Personnel department's prejudices first.

(Mr.) Erin Avery