What does a writer need to know to write documents? In my mind, there are four main knowledge areas:
What is the value of knowing these areas to an individual writer and to the documentation group in general? One way of assessing the value is to think about what the different areas bring to the end user. After all, they are the ones who pay the salaries in the end. Let’s take a look.
Knowing the Users
If you know the users of the product, you know what kind of information they need, in which media, and in which situation. This enables you to design information products that meet the users’ needs, which in turn makes the users more efficient in their work. They don’t get frustrated by having to search for hours for some information they need (not that they would actually do that) or call the help desk. This increases customer satisfaction and your company’s goodwill value.
Knowing the Product
If you know the product that you are documenting well, you know what kind of tasks the users can perform with the product. You know how it works, the bugs, the usability problems, and the logic behind the product design. This enables you to get the facts right in the documents and guide the user around the problems in the product design. But if you don’t know what the users need, you may well produce information that does not support the users’ actual job tasks, and they may not find the information they need when they need it. On the other hand, if you don’t get the facts right, it does not matter how well the documentation is structured according to users’ needs.
Knowing Basic Technical Writing Skills
If you know the basic writing skills, you are able to write clearly and use tables, lists, and figures to make the text easy to read and understand. But writing readable and understandable text doesn’t really help the users if the text does not help them in their work or it contains misleading information about the product or its functionalities. Then again, if the text is incomprehensible or otherwise difficult to read due to bad organization of the text, users make mistakes and get frustrated.
Knowing the Tools
If you know the tools you work with well, you are able to work efficiently and concentrate on the actual content instead of trying to get the tool to do what you want. The users don’t really care what tools you have used to produce the information. Knowing the tools has value mainly to the company you work for because you can be more productive than those who are less competent with the tools.
So all the knowledge areas matter, and you can’t do without any of them. In addition, I would argue that the order the areas are presented above is the order of the added value they bring to the users.
Another point of view is to rate the knowledge areas according to how difficult the knowledge is to obtain. The order still remains the same though. For example, getting to know the users well is difficult and takes a lot of time, whereas learning to use some new authoring tool is a relatively easy task.
The difficulty of obtaining knowledge also implies how difficult it is for a company to replace or subcontract the knowledge. The following graphic shows the different knowledge areas in relation to the value to the customer and difficulty of acquiring the knowledge.
If I were a writer, I would rather try to learn more about the users and products because that knowledge brings the most value to the end-users. In addition, my knowledge of users and products would be difficult to replace because it would take more time for a new person to reach the same knowledge level. If my knowledge were solely related to writing skills and tools, it would be easier for a company to get a contractor to replace me.
On the other hand, if I were a manager, I would hold tight to the writers who know the users and the products, and if I had to cut the direct costs (headcount), the tool geeks and those who concentrate on polishing the text to death could go. It would also be easier for me to subcontract those skills if I still had the money to do that and not just hire new people. Getting a person who would know the users of my product and the product itself would be a much harder task. And if the person changed from project to project, the knowledge would never reach the needed level.
This article is the personal opinion of the author and does not necessarily reflect the opinion or practice of Nokia.