We translate from programmer to Russian

Who do you think knows the product best? PM, or maybe DM? Analyst? Interface Designer? The answer to all these questions is likely to be “no.” At least in the case of a large project. Why?



Let's try to consider in more detail:



Main. He describes the concept. Says: “I want it to be blue here, and this button is reducing everything. And here, as in Windows 8 | iOS | in that application | better than the competitor (cross out unnecessary). And, obviously , it should be able to do everything in red and place small squares. ”



Analyst. He writes requirements. He knows what should be in the product. He knows how the main scenarios should work, but he usually does not go into the subtleties of implementation, because for this there is an interface designer. And this is the task of the interface designer to make the product beautiful and convenient. After all, only 20 percent of the product consists of what they will actually use, and, at 80 percent, of marketing materials, ticks, and comparisons with competitors. Sometimes it even happens that the analyst is very surprised at the end of the development of what his requirements have become. After all, as you know, during the journey the dog could grow up.

')

Interface Designer (ID). According to the requirements draws a draft interface. Ideally, a project is practically the only document that needs to be guided in its development. Is that part of the technical specifications to take from the requirements. But this happens only in an ideal world. In the real world, the interface designer does not handle various exceptional cases and errors. This should be done by the programmer. Of course, he consults with ID in difficult situations, but he usually does simple ones himself.



Project manager (PM). When the team starts to fail, it comes and in a penetrating voice asks why we cannot draw the red line in green. And then he repeatedly clarifies and replicates the information received from the developers, and it happens that through the “damaged phone”. Thus, PM is usually well versed in the problematic parts of the product, and has its own specific outlook on all of this. However, a specific view on any issue is different for any participant in the project. But you have to say something about PMs.



Development manager (DM). If the product is small (1-3 developers), he fully understands what, how and why the product does. If the product is large, then he will not have enough time to understand the details. For a part of the functional, he is forced to trust the developer-tester bundle, considering that everything is fine there. Usually, DM is well versed in difficult-to-implement parts of the product and worse - in simple and well-described interface designers.



Testers . Ideally, each tester should superficially know the entire product and very well - its own subsystem. In an even greater ideal, the subsystems would be good to change between testers so that their eyes are not blurred. TM (testing manager) in this sense is very similar to DM, and often discovers things that are amazing for themselves, already known to others. Since among the editors of the blog there is a tester, he was able to convince the author that the tester in charge of the product knows the whole product, so I had to cross out the paragraph.



In total, each of the above participants in the development process is well oriented in its own “glade”, but most often it does not have a complete picture of the product.



So who is the man who knows everything? This is a technical writer . The work of a technical writer is not only difficult and time consuming, but also responsible. Tehpis must make the same things, made by different people, called, firstly - the same, and secondly - correctly. He says "incomprehensible" and goes to find out what is happening in this place of the program. It is he who, in the end, should invent new features based on incomplete descriptions of the developers and formulate texts describing the complex places of the program. He is a translator from programmer to Russian. A technical writer should come up with a clear, beautiful, and most importantly - a short text to the functional, which, perhaps, is not quite well designed or implemented.



By the way, do you know the fastest way to make a product better? Of course, rename the buttons! Here is an adaptation of the famous vonvogel comic on this topic:



What else? Tehpis checks the integrity of different parts of the interface and their consistency. And he writes a certificate. And he writes so that it is clear even to the hedgehog. Therefore, the task of a technical writer is to write a good reference. In which the user will always find the answer to his question, this answer will be clear, and the search for it will take a minimum of time. What does this mean in practice? The help structure should be intuitive and as simple as possible. The text should be easy to read, phrases should be unambiguous and as short as possible. It is necessary to avoid complex constructions, the text should be well balanced - not too simple and not too heaped up, not poorly lexically, but not full of flowery expressions. You need to be able to explain complex things in simple words. In order not to confuse the user, the uniformity of the style of presentation and design should be observed. Help must correspond to the product, i.e. It is necessary to describe the new functionality, delete what is no longer present, rewrite what has changed. And all this in conditions when the program is either not yet, or it has not been tested, or is not debugged. Therefore, it is impossible to see what works.



Here we recall the story of how many, many years ago we produced a product for the needs of state institutions. The product was defective at that time - neither an analyst, nor a designer, one programmer and a tester. The fact that the new version is necessary to update the documentation, remembered a couple of days before the release. Everything would be fine, but the program at that time was not installed and not started. Describing the new functionality from the words of a developer for an experienced technical writer is not a problem. But we remember that the program for government agencies, right? And as we know, middle-aged aunts, who are not friends with computers and are afraid of everything, work in them. We, of course, try to help them, hence the incredible number of screenshots in the help. As a result, we get the picture: the programmer is trying to finish the product, the tester is running, PM is running from one to the other, asking if we can fix it all today and test it or not, and the technical writer ... rules in Photoshop graphic editor 1 for 2 in the program version on a hundred screenshots.



And technical writers make user guides, admin guides, quick user guides, and more. Each document has its own purpose, which means its own features and nuances.



And we also produce products for different countries, so technical writers do not have to be bored at all - programs need to be localized in many languages, good and different. It is the technical list that collects all materials for translation from us, checks them, builds them into the product, makes changes arising in the course of development. Read more about the seriousness of the process here .



There is another story. We released FineReader N a number of years ago. With the file, we had everything as it should be: analysts analyzed, designers drew, programmers implemented, described the specifications and everything was translated into 22 languages. And here on you - beta testing. And the users tell us (or rather, even one user, or rather, user number one): “And give us two teams, well, we just can't live without them. Yes, at the same time, remove the two extra scenarios. They asked DM how long to change. “No,” he says, commenting out two lines and uncommenting two. Everyone was delighted, except for technical writers. They needed to make changes to the program's resources, to the help, to the user manuals (which were already put together at this point), to the QRC (also known as Quick Reference card or quick dating card), to re-take part of the screenshots ... For one language, 49 edits were made. Multiply the number of languages ​​yourself (picture from MKrivosheev can help if calc does not work. Video explanations for the picture ).



It turns out that, ideally, every technical writer should simultaneously be a little analyst, designer, tester, and sometimes also a programmer (technical specifications and products for developers describe, for example, such ).



As a result, a technical writer is such a superman (although most often super-smart) in the development team. It should be both a humanist and a techie at the same time, have a basic understanding of programming and information technologies, and be able to understand a wide variety of programs, from simple (for example, Word) to fairly complex (for example, Visual Studio). He has to be meticulous and attentive to trifles, but at the same time see the whole product in order to understand how best to describe it. To be able to clearly plan your work so as not to sink into the sea of ​​your tasks. I am obliged to be fluent in written language and know English, at least at the level of reading documentation. Let's not forget about stress tolerance, the ability to work in the workmanship mode, quickly switch from one task to another, and a lot more. In general, a good technical writer is a piece goods. So love your technical writers, take care of them and help them in every way. For without them, your products will be a little miserable and tongue-tied, and with them you will have happiness, money, success. Well, or at least a good product.



Ivan Korneev chronomaster with the participation of Elena Fomenko,

Department of products for text recognition.