To err is human, to forgive is divine. The problem lies in the fact that users are also human and they are not used to forgiving – especially people like product designers, developers, and writers. This can be attributed to the variety of choice available to the users. They can happily switch to another product if a particular product fails in any aspect. A user might also be dissatisfied if the product is very good but lacks meaningful help information to use it comfortably.
Here is a list of some common mistakes that technical writers often commit. Instead of relating to the grammatical, syntactical and style mistakes associated with writing, this list focuses on the roles and responsibilities of a technical writer. It is broadly classified relating to the three major actors – subject matter experts, users, and writers – who play a significant role in the development of an effective Help system.
Mistakes with regard to subject matter experts
- Waiting to hear from the developers. Technical writers need to be proactive and try to gather information from the various subject matter experts. It is very fortunate if the software development process includes documentation as a significant part and there is a separate deadline for submitting the different drafts of documentation during the different stages of product development. Yet, it is the responsibility of the technical writer to step forward and fix an appointment with the Project Manager and seek permission to interact with the product designers and developers.
- Not planning the interaction with the developers. Technical writers and developers are often at loggerheads when a deadline is due and a new feature is added to the product. The developer has to complete the assignment within time and the technical writer has to gather as much information as possible within the short period of time. None of them can compromise on the quality of work that they do at this juncture.
- Looking at things from a singular point of view while interacting with the subject matter experts. You need to look at things from the developer’s view and the user’s view as you interact with the subject matter expert. This helps you get the different perspectives and gain complete knowledge.
- Approaching a subject matter expert without any preparation. Technical writers often fail to respect the paucity of time and other constraints that developers are associated with. It is very difficult for the developers or the design team members to explain in detail every trivial aspect that can otherwise be easily learned through one of the search engines. Hence, technical writers should walk the extra mile and do a little amount of research and preparation even before approaching the developer. Likewise, they should clearly absorb all the information available in the design document to get a hang of the product.
- Not asking enough questions. It is advisable to prepare a list of questions even before approaching the experts. This helps gain clarity about what one wants to gain from the interaction. Some interactions might last only for a few minutes and the writers need to collect the most important information. Hence, it helps having a list of questions. It is also good to send the list of questions prior to the meeting so that the developers are also ready with the answers.
Mistakes with regard to the User
- Having too much information that overwhelms the user or too less information that confuses the user. Writers tend to justify when they are unsure of what information to add and what not to add. Imagine yourself as the user. List the inputs that you want when you try the application for the first time and at later stages. This can help you arrive at the actual volume of information that neither overwhelms the user nor leaves him confused.
- Making assumptions about the audience and going ahead without any clarification. Draw a clear line between observations and assumptions. Inferences can be drawn only if the source of information is authentic. A senior and experienced project manager might give you some authentic information about the probable type of users of a new product. Likewise, an industry report about changing trends can also be a reliable source. More often, you are not sure of the audience. Instead of making assumptions, try to interact with the actual user to get some understanding. While this may be impossible mostly, you can infer about the audience after interacting with the developers and other key people involved in the product design.
- Ignoring the way users tend to use the product. While every writer speaks about getting into the shoes of the users, very few actually do so. It is difficult to look at things from the user’s perspective. This is mostly because of the heterogeneous nature of the users. But, one thing is true for sure. The way the user uses the product is different from the way in which the developer uses it. Hence, do not stick to the developer’s viewpoint.
Mistakes with regard to the writer
- Believing that they know everything about the product by just trying it. Writers also need to know what happens in the background. Some writers believe that it is enough to learn as much as is necessary to convey to the user. But, to convey that information effectively, writers need to know what happens in the background and a lot more about the product before beginning the process of documentation.
- Living under the impression that writing is a fairly simple process. Yes, writing is not as simple as it seems. If a writer has to just construct grammatically correct sentences and deliver them to the user, it would not make any sense. Technical writers need to understand that there is transformation of knowledge about the product and it should be done as a process. Any slight deviation might disrupt the entire flow of knowledge from the writer to the user. It is for this basic reason that some companies designate technical writers as Information developers. They need to develop information that the user can use to carry out his work with the product.
- Ignoring product development meetings. Even though it is not necessary to participate in every meeting where technical elements are discussed, it would be useful to attend meetings such as design meetings, product demos, and presentations that help writers gain a lot of knowledge and save a lot of time.
- Assuming that it is not necessary to know about technology. Writers come in different sizes and shapes. Some writers who hail from a literature background fail to understand the importance of keeping in pace with technology. They find it a sheer waste of time to learn more about technological advances.
- Lacking interest to learn about other product developed within the same company. While it may not be necessary to know about other products that you need not document, it helps a lot to exchange common information whenever necessary. If you are up to date about where the information might be available, it saves the time invested for searching for information.
Ultimately, writers need to realize their role as a part of the entire software development system and that they are not isolated to come up with beautiful sentences and catchy phrases. People have started recognizing the significance of technical writing as a domain the way product design, testing, and development are considered.
