As technical writers, our main goal often is to write instructions so the end user will understand how to use the product for their specific needs. This sounds easier than it usually is in reality, because the end-user point-of-view is ephemeral and hard to maintain. Many of us are familiar with the argument the longer we spend documenting product, the harder it is to see it from the end-user perspective. On the other side is another argument, if we have no contact with users, it’s infinitely more difficult to write appropriately for them. So this begs the question:
How close should a technical writer be to an end user to properly write instructions for them?
If technical writers are too far removed from how an end user works and wants the information, then they will not write the instructions in a way the end user finds usable. However, if a technical writer is too close to the end user, the instructions tend to become vague as the writer accommodates more assumptions about what the end user already knows.
To write the best documentation possible, I walk a fine line—between working with programmers and understanding end users—to write useful instructions. Although I have the opportunity to learn everything there is about how the software is programmed, delivering that much detail can cause the documentation to sound too technical and be no good to the end user. I need to talk to the programmers to get enough information to know how the program processes data, and what text goes into what fields, so I can teach the end user what to enter.
Being the Generic End User
Technical writers are hired into projects at all different stages. Many times, I have been added at the end of programming when the project is already in beta testing and on the way to being sold. As a result, my main goal is to learn the software in its entirety and write instructions from the view of an end user—the result of the most basic kind of user analysis. Sometimes, this can be the easiest way to write. I essentially write what I would want to know about the software because I am using the software at the same point an end user would be – without having any bias about the usability of the software.
Serving a Specific End User Group
I was hired by a software company back in 2008 that is now in the middle of the development stage of their software. I work closely with the programmers as they create new modules and debug the program. A manufacturing plant is currently beta testing the software and receives new updates each week. The staff at the plant specifically directs how the software is programmed by providing regular feedback. As a technical writer in this situation, I have a direct relationship with this group of end users of the software, and indirect relationship with all other end users.
I regularly talk to staff to learn how they perform their jobs and translate that into instructions for the software. This relationship poses certain challenges, because I make the assumption that this specific end user already knows the software as they direct the programming of it. However, since this software will eventually be the marketed to other manufacturing plants, I must write the software as if I do not have this specific relationship. It’s easy to become biased—writing to a specific end user at this plant—when someone in a position at another plant may not do the job the same way.
When I talk to the staff at the manufacturing plant, I discover they have certain expectations for software functionality that are not possible from a programming standpoint. The company must balance the needs of this manufacturing plant end users, with the requirement to sell the program to other customers in the future, so it cannot be so specific to this company’s user roles that it would be useless in other plants. Thus I have to avoid getting so wrapped up in what the beta users want that I write only software documentation relevant to a specific job title at this specific company. Knowing how these end users use the software teaches me what the software should do from the end user perspective, but my instructions need to be general enough that anyone wanting to use this software would be able to understand how to work with it.
Although a technical writer’s line between the technical and the layman can blur at times, writers must find the happy medium so the instructions are of benefit to anyone, at any level of expertise, who wants to use the software.
Fellow technical writer Geoff Hart points out that doing user, or audience, analysis, asking open-ended questions to an end user may create biased answers. He also states that too many questions to an end user may become annoying and cause a bad professional image. Because of this, Geoff recommends putting a set of procedures in place and discussing carefully with management to protect the company, its image, as well as the confidentiality of the material.
This reminds of a line from the movie Apollo 13 to think about when writing documentation. “I don’t care what it was designed to do, I care what it can do”. Programmers primarily care about how to design the software, but end users want to know what the software is capable of doing so it can be manipulated to fit their individual goals.
Early in the process of writing software documentation, I make sure to talk with the programmers to understand how it is designed to work; what type of information to enter in each of the fields; and how the software is designed to return results. When I job shadow an end user of the same part of the software, I discover what the end user expects to enter in each field and what results they expect. A good balance between interviewing SMEs and user analysis results in documentation that meets the end users’ needs.