work of a technical writer is dedicated to my favorite Russian technical writers - to create documents for software products, basically all kinds of user manuals. Developing a document is not easy. There are many approaches and practices. For example, technical writers in scientific and industrial enterprises often write according to GOSTs or other domestic standards. Their goal is to accurately and correctly describe the product. And technical writers in international companies write according to style guides (Microsoft Manual of Style, for example). In this case, the goal is rather to convey to the user how the product works. Here the focus is shifted from the product to the reader.
I've been a tech writer in different places, with different rules and policies. Looking back, I can say that even in research institutes, texts can be reoriented towards the end user, and documents will benefit from this. But they don't write about it in GOSTs. And style guides, firstly, in English, and secondly, are not advertised in domestic offices such as NPP, KB, etc. Therefore, there is an obvious lack of information. I will try to fill it up.
How do the docks for Yandex, Google, Microsoft, Apple products differ from the old-school documentation created by design engineers?
A classic engineer writes so that the product is described as fully and correctly as possible + in accordance with GOSTs and accepted terminology. Moreover, many terms and definitions in GOSTs are outdated and do not color documents at all. But this is not a problem for constructors - no one thinks if the text is easy for the user to understand. But docks made for people are different: they are written in understandable language and take into account the interests of the user. A matter of priorities.
These priorities and goals of the author greatly influence what documents are obtained. Let's see with examples how it looks in real life:
| Design approach | User-oriented
|
|
|---|---|---|
| Simplicity of terms
|
Click on the folder icon by LMB click of the mouse.
|
.
|
|
|
20- , , . .
|
, , . |
|
|
. «». , . «».
|
. |
| , . . , , .
|
, . , .
|
|
|
|
. – , .
|
: , , .. , .
|
|
|
: , , , , .
|
, . , . , , .
– . – . , . |
It happens that you look at documents, and they are already morally outdated. It's like reading the manual for a 1950s tractor. We need to somehow make them more relevant, but it seems impossible. In fact, anything is possible. In the following articles, I will analyze step by step how exactly to move from a huge outdated set of documentation to light, understandable, modern docks. We will analyze each of the points in the table in a separate article.
Spoiler
It won't be easy.