Gerry Butterwick
(email me at gbutterw@emich.edu)

Portfolio Introduction

The primary challenge of computer documentation:
User-centered writing
If one could say there was a single major theme of our studies this semester, it would be the idea that computer documentation is not something that someone reads to find out what a particular piece of software or hardware can do, but rather, computer documentation is what someone reads when they're trying to find out how to use the software or hardware to help them accomplish the task at hand. When someone writes computer documentation, they are not writing ad copy. You don't need to sell your customer on your product; if your customer has already purchased your product, your job is to make it relatively easy for your customer to use the product for whatever it is they need to do. While that makes sense, every one of us in class, and many people I've met in other areas of my life, have all come to view computer documentation as a genre of writing that seems to tell the reader everything except for what they need to know. Oftentimes, the most useful piece of information in computer documentation is the phone number for Tech Support. Frustrated users need a "human being" to talk to.

Supposedly, there is a human being out there somewhere who is somehow responsible for the impenetrable prose of the documentation that sends users to their telephones, but what, exactly is the nature of this failure, and what can we, as Technical Communication students, learn in order to make documentation that "stands on its own?" The nature of the challenge is two-fold: on the one hand, documentation needs to be specific enough so that a user can rely on it to solve the real-world problems he is likely to encounter. On the other hand, documentation needs to be somewhat general, just for the sake of concision and clarity. The technical writer who can achieve that balance is the one whose documentation will be read, and used. The company that recognizes the importance of writers able to produce good documentation will benefit in ways far more meaningful than the first-sale profits inspired by effective ad copy. The company will have begun to earn the trust and respect of its customers, which, in the world of computer products, is a rare thing, indeed.

My own interest in computer documentation: stumbling into the light
Part of the challenge in computer documentation isn't always in the information that's presented, but in the way that information is organized. We spent a great deal of time in class talking about how we, as aspiring technical writers, should strive to leave out any information our readers don't need, but another crucial goal for technical writers is to present information in a way that is logical, and reflects the way the audience will actually use both the product and the documentation.

I spent seven years as a database administrator at TRW Automotive, and in that capacity, I read an awful lot of technical documents: Engineering Change Requests, work instructions, product specifications and software documentation. I've used hard copy documentation, on-line help and the phone number for Tech Support. Many times, the most use I've gotten out of any documentation has been the serendipitous discoveries of information that was helpful, but not what I was looking for at the moment. I don't know how many times I had the thought pop into my head, "Oh, that's interesting. Not what I need right now, but interesting." Optimal organization of material has got to be one of the most important things for Technical Writing students to learn. Like the best technical documents, however, learning how to best organize one's material isn't as simple as following some step-by-step guide on how to do it. It requires putting oneself in the place of one's audience, so users don't find what is helpful to them by happy accident, but by design.

The Team Print Tutorial: Using the Table feature in Microsoft Word

Background: the situation in which the tutorial came into being

For this assignment, we were split up into groups of two or three. My group consisted only of myself and my partner, Pamela Malski. Unfortunately, because I suddenly took ill with meningitis six weeks into the term, Pamela ended up being responsible for a relatively large portion of the work on this project. I did, however, make some contributions, particularly in the overall design. We took as our task the creation of a tutorial about inserting tables into Word documents.

Reflecting on the Print Tutorial Project

Applying the user-centered documentation appraoch
This project did provide all of us in the class the first opportunity we had to apply the concept of a user-centered approach to writing computer documentation. Since we were encouraged to think of our projects as something that could potentially be of some real use to other Technical Communication students, we decided to focus on the creation of tables in a Word document. Since I had actually found the need to incorporate tables into an assignment I had done in a previous Tech Comm course, there was a ready-made scenario for us to incorporate into our work. In the original assignment I had done for my ENGL324 class, we were to put ourselves in the place of someone who had to condense several paragraphs of information about two different forklifts into an easily-digestible, one-page memo. This gave us an opportunity not only to discuss the general advantages of using a table in a document, but it also allowed us to make something that might meet the needs of other Tech Comm students.

The two sides of every table: the author and the audience
One of the more important ideas that came out of this project was the notion that there are two main advantages to organizing information into tables. First, the table helps the author to make sense of a complex assortment of data. It can help an author to make sense of what she is trying to get across, particularly if much of the data is numerical. The other main thing a table does is to make things more clear for a reader. Certainly, tables are not "read" the way articles and essays are read, but they can be a succinct and powerful way for an author's audience to get a more clear idea of what an author is trying to get at. It's hard for me to imagine certain books that discuss ideas in physics or statistics without some tables in the documentation to bring order to what would otherwise be very difficult ideas to get across. While the step-by-step, instructional portion of the tutorial was essential, the conceptual framework, the idea about tables helping both authors and audiences, gave the tutorial its academic value. The conceptual framework also gave the tutorial versatility, for the issues raised in relation to the "forklift" memo could be applied by technical writers to many other situations: in the classroom as well as in the workplace.

The Individual Online Tutorial: Mouse Instructions

Contextualizing the Online Tutorial Project

In the case of my online tutorial, I kept things pretty simple. I wrote the short instructions based on a user task no more sophisticated than the need to bring an image from a web browser like Safari onto the user's desktop, and from there into a Word document. It's the kind of procedure that most novice computer users want to know how to do, and I geared the tutorial toward the type of user who isn't very experienced, but has something specific they need to do.

Reflecting on the Online Tutorial Project

Again, the user-centered approach seems to be the most effective way to communicate to people who want to use technology to do something, rather than learn all the workings of their machines. That really sums up most users. One doesn't really need to know too much about the inner workings of a car to be able to get from one place to another, and most user's experience with computers is roughly the same as most driver's experience with cars. Once you start bombarding the person relying on your documentation with a lot of extraneous information, you're not just risking losing that one person, but you've created a potential systemic problem for your developers, your company, and your customers.

I'll admit that it took a while for me to get sold on the whole idea of a user-centered documentation approach, mostly, I realize, beacause I simply hadn't seen it before. But as I saw what was being done in terms of usability research, and the successes of bridging the gap between those who supply technology and those who need it, it slowly started sinking in that a user-centered approach is really the most effective way to write and to conceptualize documentation. Part of the reason I kept my task so simple is because I felt the need to get down to basics. If I'm a novice user trying to put a picture I see on the internet into a report, how do I do that? The even more important question to ask, of course, is why would anyone want to do that? Attempting to answer that question brings us to some pretty challenging ideas: What is the purpose of illustrations? How can visual means of communication be improved? Why do some attempts at visual communication work better than others? Those are the big questions that go to the heart of what we try to do as technical communicators: convey ideas in the most effective manner possible. And the only way to do that is to have some understanding of the people we are trying to reach.

The Focused Usability Test Project: Usability Shootout

Contextualizing the Focused Usability Test Project

In what was referred to in class as the "Usability Shootout," all the themes of the current semester came together in this single project: the importance of focusing documentation on user tasks; the need for technology to support the types of things people need to do, as opposed to being an end in itself; and the idea that the Internet is not only a valuable resource, but a venue in which technical writers themselves can reach new audiences. Of course, new audiences will no doubt bring with them new expectations and new priorities. The success of any online enterprise, be it a business, non-profit agency or university graduate program, will be measured by how well the enterprise anticipates, and fulfills, these changing expectations and priorities.

Each person in the class was expected to find a participant willing to look at two websites for graduate programs in some field of Technical Communication and answer questions regarding the site's usefulness and usability; that is, how relevant the sites were to the participant's interests or needs, and how well the site facilitated the participant's ability to find what he was looking for in terms of those interests and needs.

Reflecting on the Focused Usability Project: the many faces of an institution's web identity

Ideally, any school with a graduate program, and an online presence, is going to appeal to a variety of people: faculty, staff, businesses, alumni, current students and prospective students. The study participant, taking on the role of prospective student, is accomplishing two things with their involvement in this study. He is assessing the graduate program itself, and he is trying to get a sense of what one might call the "character" of the school based on the way the school chooses to present itself to the greater community, and specifically, to the community of prospective students on line.

What's interesting to see are the ways in which schools clearly try to manipulate their image online, and the ways they occasionally inadvertantly reveal more about themselves than they had perhaps intended. One of the real benefits of bringing in participants from outside our discussion group is the opportunity to see how certain issues and themes get raised again and again. Thoughts about audience, marketing, even color pallets resonate in all of the research done by myself and by my classmates. An online presence consistantly tries to say, "This is who we are," and "This is who we're hoping to attract."