How “interface” differs from “intermordia”: our approach to documenting and localizing software products

Once in the technical documentation for Parallels Desktop, we needed to use the phrase “ virtual hard disk ”. In English, it sounds: virtual machine hard disk . Our past technical writer made a mistake in just one letter in one word, but the meaning was diametrically opposite. We noticed this not immediately and at some point our technical documentation, localized in many languages ​​of the world, contained an imperishable: virtual machine hard dick . There was a huge scandal, after which we tightened the verification of texts. Under the cut is the story of our technical writer Andrei Starovoytov about where technical writers live, what to catch them and how Parallels documents and localizes their products.

Perhaps you have a question - why should I, the developer / programmer / tester, know how the documentation and interface are created and localized? Everything is very simple: life can suddenly turn to you so that today you are a programmer, and tomorrow you start your startup in which you are a Swiss, a reaper, and a technical writer. It is also possible that taking up a managerial position you suddenly have to control the process of developing technical documentation.


')

Part 1: Where to find a technical writer or a humanist in the rear of techies

Technical writers are not trained in universities. If you need such a specialist, you can invite him from abroad, or "grow" in the company. Below we will focus on these options.

Foreign specialist

Pros :
If you plan to sell the product abroad and you need documentation in English, the native speaker will describe the application more qualitatively. It cannot be said that a domestic employee with knowledge of the language will make it necessarily bad, but if you approach the issue from the point of view of perfectionism, then for some phrases, turnovers, sentence building, foreign users can understand that the documentation was not written by the carrier.

Cons :
First, the foreign specialist will have to pay more. And secondly, not every foreigner agrees to come to work in Russia. If he works remotely, apart from the developers, then there may be delays in the preparation of documents, and technical inaccuracies, since remotely it is always more difficult to find out the technical details than if you talk to programmers directly.

Writer "who raised"

Then the question arises, from whom to grow - techie or humanities? Of course, it all depends on the specific situation, but let's look at the main points.

"Techie"
Pros :
The technician better understands the filling and technical details, or it is easier for him to understand.

Cons :
Not every techie will want to mess with the documentation, because the developer often concentrates on a narrow area and sees himself as the Sculptor, rather than Yevgeny Onegin, "who can touch on just a little with the scientific appearance of an expert."

"Humanitarian"
Pros :
It all depends on the case, but the humanities can better describe the product, as it is better able to speak the language. And another such moment, the developer can describe the function or feature in two sentences, because with his baggage of knowledge he already understands everything. For the buyer of the product such a description may not be enough. The humanist, as a non-expert, will have various questions when describing. If he finds answers to them and describes the function of the product so that it is clear to himself, then such documentation will be more understandable to the user. Although again, it all depends on the specific situation, if the manual is written for administrators, it would be unnecessary to explain to them what an IP address is.

Cons :
The minus of the humanities is that he knows less about the technical side of the product, and it will take time for him to master the terminology, master the basics and begin to understand what's what.

Personal experience
- I got into Parallels very prosaic. After school, he studied at a teacher's college in the city of Serpukhov as an English teacher. After at the Moscow State Linguistic University. Maurice Thorez. When in the third year of university the question of serious work arose, I had already been a courier to deliver a DVD, a stock clerk at the warehouse, a warehouse manager, a sales manager. All this was good, but the desire to make a living in English was stronger. I didn’t go to teaching, because I wanted to work in some applied field - oil industry or IT.

Once I saw a vacancy on one of the job search sites - an assistant technical writer at SWsoft with a career opportunity. The announcement said about participation in the creation of documentation for computer programs. Writing documentation was required immediately in English. For me it was something completely new and interested. I sent a resume, had an interview, wrote an essay on a free topic, and so became a junior technical writer.

At first it was not easy. Being a humanist to the bone margins, when writing the first topics, it seemed that everyone around was speaking some bird language. I absolutely did not know the terms. The conversation with the developers at first looked like this :

- Hello, I am a new technical writer. I need to describe this functionality. Could you tell us in more detail how it works?
- And, well, everything is simple, the client “connects”, if the “server” is not dead, everything is fine. If anything, you can "ping". It happens “the bug shoots”, “the container is bosoditsya”, but here the “patch” can be rolled. Take this "executable", it is on the "turnip" for testers. Got it? Well done.

or so:

- I need to describe a feature here, it is connected to Active Directory. Could you tell what it is?
- Yes, this is the same as LDAP on Linux.

At first I wrote down all these terms in a notebook, then I went to “google” the meaning. After that, I again went to the developers or testers and asked for a new one. During the first six months, during my free time from work and study, I studied terminology, read about automation, virtualization, containers, virtual machines, RAM, processor, IP address, DHCP, etc. Then, suddenly, the quantity turned into quality and I I became freer to feel in this area. If I didn’t understand something, I had enough Google to grab the main idea, and to the developers it was already mostly for the details.

At the moment I have been working in the company for about 8 years. Grew to senior technical writer. Now I am engaged not only in creating documentation and interface, but also in their translations into supported languages.

Part 2: How we create technical documentation

We have 3 people working on the creation of documentation - two in Russia and one employee in the United States, for whom English is native. For writing technical books we use the product AuthorIT . It is quite convenient to work in it. Library with books is on the server. Every writer on the computer has a client part with which he connects to the library. This allows multiple writers to work on one book. The use of options makes it easy to create books for new versions of products based on old ones.



It's hard for me to say anything about other products in which you can create documentation, because historically, we work at AuthorIT. He is satisfied with us so far, and switching to another product just out of curiosity may turn out to be an expensive pleasure. For example, the same AuthorIT subscription for 3 people will cost $ 375 per month and higher.

Since our main market is located abroad, we write the documentation immediately in English. Since now in the world English is considered a universal language, special attention should be paid to the fact that there are no problems in the English documentation. Of course, it would be possible to write in Russian, and then translate into English, but this would make it necessary to check how well the translation was made.

We would not like to spend resources on it, since we have the opportunity to write immediately in English and at the same time check that this English is understandable and looks as if the text was written by a native speaker.

The process of creating documentation is as follows:

1) Marketing managers discuss the list of features and improvements that will be implemented in the new version of the product.

2) For each task, the manager writes a detailed description.

3) After the programmer introduces the functionality, I put the latest version of the program on the computer, read the description, try how the novelty works, and describe it in the manual. If you have any questions, communicate with managers or developers.

4) I describe the new functionality in English, and then send the topics to our foreign writer for review. He reads and, if necessary, makes any changes. It seems that I know English well, but anyway, a native speaker can sometimes be expressed more succinctly and succinctly.

5) After verification, the foreign writer sends the topics to me, I upload them to the database and publish documents in the required formats - mainly PDF and XHTML for context-sensitive help (this is when you click on the screen with a question mark and the topic attached to this screen opens in the browser).

6) When the English documentation is ready, I send it to the translation. About how and what languages ​​we translate, I will tell below.



What documents are created for the product:

The User's Guide is the largest book for a product that describes all the functionality, tricks, and solutions to possible problems. It is targeted at most users.

The Getting Started Guide is a short document that describes the installation procedure and the basic steps necessary to get started with the product. Focuses on familiarity with the product and users who have some experience and want to quickly start working with the application, not embracing additional settings and subtleties.

A readme is usually a text file that is created for each release, hotfix, and update. It describes what has been done new, what has been improved and what problems have been solved.

Knowledgebase articles are articles for the so-called knowledge base. They describe either some points that cause frequent questions from users or temporary solutions to known problems.

There are also various other types of books, such as:

- Licensing Guide (describes how to create an account, manage your key or subscription, etc.)
- Administrators guide (document for people with technical experience for product deployment in large companies)
- Training manual (document for people who teach users how to work with the product)
- Command Reference Guide (it describes the commands for the text line and gives examples of their use)
- API Reference Guide (in such books document the API).

What tools we use to create documentation:

- AuthorIT - a program for creating and working on books.
- Adobe Photoshop - to create and work on screenshots for documentation.
- Microsoft Visio - to create schemes.
- Microsoft Word and Adobe Acrobat - for publication of documents in the .docx format and the subsequent generation in PDF.

There are various curiosities in the work of creating documentation. Mainly related either to the writer's inattention or if something is being done in a hurry and trivially missed. For example, there were cases when the finished documentation was released, in which there were not deleted comments of the writer, for example, “To clarify with Vasya how this garbage works”.

And sometimes it happens that the writers themselves are kidding in the documentation for internal use. Some people think that no one needs documentation, since nobody reads it. Sometimes a writer in some non-official document for a company can write in the text of instructions - “who is the first to read it and call me - will win the beer”.

Part 3: How a technical writer can be involved in creating a GUI

In the process of working on features, developers often have to come up with the name of the option, menu, descriptor under the option, or an error message. Since we are doing Gui right away in English, developers assign this task to me. I read the description of the feature, ask the developers and managers what we need to say, find out the details and offer my English version. If he is technically correct, send him for approval to our foreign writer and inform him of all the details that he found out from the developers. He, in turn, either approves my version or offers something of his own. If the final version suits everyone, it is poured.

In the process of creating gui, we adhere to the following points:

1) One should try to make the names of the options clear and short in order to avoid subsequent problems with their localization when the translation does not fit. For example, we have an option that slows down the mouse cursor at the border of a virtual machine window. This was done to make it easier for the user in Windows 8 to open additional menus that are near the border. Without this option, the user often just took the cursor over the border and the border menu was not displayed. So, for a long time we thought how to call this option, it turned out to be either too long or not entirely clear. As a result, stopped at "Mouse sticks at window edges". Of course, there are cases when it is difficult to come up with an ideal name for the option, in such situations you have to choose a more or less acceptable option and hope that if the user does not understand, he reads in the documentation.

2) If the message uses complex terms or describes a laborious process of how to solve a problem, it makes sense to give a link to a CB article or some other resource where there is a more detailed and detailed description or explanation.

3) When creating a message, it is necessary to concentrate not on what did not work out, but on what needs to be done in order for the desired result to be achieved.

Part 4: Translation of technical documentation and GUI

After the development of a new version of the program has begun, usually the first batch of help topics and gui phrases are accumulated to Beta 1 / Beta 2, which can be sent to localization.

In my opinion, it’s very cool if the same writer who wrote the topics and helped to do the goo, and will manage the translations and communicate with the translation office. Such a person correctly plans the work, knows better the time when it will be written or how soon something needs to be described. He knows the meaning of the guyev phrases and can answer the questions of translators more easily and quickly.

I remember we used to use the separation - there are people who write, and there is a person who deals only with localization. As a result, the processes were not always effective. For example, writers described features, their Jaskas in Jira closed and calmed down. But forgot to mention all the topics that have been changed. As a result, the localization manager sent for translation not everything, and as a result it was necessary in the wild haste to translate the missing. Or the localization manager sent a gui for translation, but he did not create it, and cannot answer the numerous questions of translators. He starts to jerk different people, but they still need to be found, because part of the Guy made the server a team, some - devices, some guevshchiki, some - integrators, in short, wasted time and not detailed answers - as a result - insufficient translation quality.

We translate the documentation and gui of our products into the following 12 languages: German, French, Italian, Spanish, Polish, Czech, Russian, Portuguese (Brazilian version), Japanese, Korean, and two Chinese versions - simplified and traditional Taiwanese.

Then a question may arise - how is it better to have your own translators or use the services of a translation company. Let's look at the pros and cons of both options.

Own translators

Pros :
If translators are in your staff, they usually know the product quite well and thanks to this they are able to make better translations.

Cons :
As a rule, the most active stage of product development, when you need to do a lot of translations, lasts 3-4 months. In such a situation, everything must be counted, because it may simply be economically unprofitable to keep translators on an ongoing basis.

Translation office

Pros :
We send them tasks when development is in full swing, and pay only for the implementation of these tasks. In the end, this is cheaper than having 12 translators in the state.

Cons :
Often, the translation office works not only for you, and today one translator can do your order, and tomorrow it's completely different. He may have absolutely no idea about your product. In order not to lose in the quality of translations, one has to write many explanations for translators, so that they have an idea of ​​what they translate and what to pay attention to.

We use the services of one of the European companies. She has her own body of translators in different languages.

All text materials are sent to the contractor. Formats can be very different:

• when GUI is localized - .txt files, .strings files, .xml files, .xliff files,
• when localizing documentation - .docx files, .xml files

First you need to localize the GUI. For each portion of gui to translate, I prepare detailed comments for translators - for each phrase. In the comments I describe what this phrase is, how to translate it - as an infinitive or imperative, whether it is necessary to translate as short as possible (especially if it is a button) and if so, how many characters should fit. Also I send translators screenshots so that they can see how an option or message looks in a goo.

Why first of all it is necessary to translate Gui

The fact is that translated phrases fall into the so-called translation memory - translation memory. From this memory, they will be taken later, if in the subsequent portion of the phrases there will be exactly the same translation. For example, we translated gui and settled options along the length. After that I send documentation for translation, in which the same options are described. So, the translation of these options for the documentation will be taken from the translation memory, and thus the phrases in both the goo and the documentation will be translated the same. If I first translate the documentation, and then go, then if the option is too long in a goo, I will have to edit it in the gue and in the documentation so that it is consistent throughout, and this is unnecessary haemorrhoids.

As soon as they are ready, the translators send me the translated materials, I import them into the bases, from where then localized gui and documentation get into the build.

How does the translation office work?

Having received materials from us, the contractor runs them through its database of already completed translations - the so-called translation memory. The system is looking for whether there is data in the new material that was once translated. As they are found, these fragments are inserted into the text. Suppose if three of the four sent paragraphs have already been translated for the previous release, then it is enough to translate only the fourth paragraph, and the rest to take their database. It saves both time and money. So the longest portions of materials are translated the longest, where the most changes and new text are.

There is one peculiarity in working with localization companies: they need to send as much material as possible at a time. If you make orders that are too small in volume, it can be much more expensive.

Why it happens?

Each localization company has its minimum amount for translation. If, after running through their database, it turns out that too little text needs to be translated, then the invoices are issued not for the translated words, but for the hourly work of translators. And since, with the approach to the release date, the portions of texts that require localization are getting smaller, you have to maneuver, holding the materials in order to save more and not overpay. At the same time, it is important not to disrupt the deadlines by sending out a large order for translation a week before the release.

Localization cost

Probably, you are interested in, how much do companies spend on localizing their products? It strongly depends on the volume and the selected languages. For example, the cost of translating one word into Polish is $ 0.14, into German - $ 0.23, into French - $ 0.21. We have large and complex products, with weighty documentation that needs to be translated into 12 languages. Therefore, the total cost of localization on average is $ 10-60 thousand. And this does not include the cost of translating articles from the knowledge base (knowledge base), which describe various methods of work, as well as the localization of changes on the site.

"Gentlemen believe the word"

Given the variety of languages ​​and the high cost of the work, how can you evaluate the quality of the translation? But what if the contractor just drove the text through Google Translate and filed the result?

The fact is that in the field of localization is extremely important reputation. When companies are looking for contractors to translate documentation and interfaces, they approach this very carefully. For example, we chose from about 15 companies: we sent out test tasks to everyone, and then we checked the translations made by our employees from different countries who understand these languages. We also paid close attention to reporting on the work done: how much detail was written, how many words were translated, how many new words were found, whether cases are considered when only part of the sentence needs to be translated, and so on.

In the end, we chose one of our companies as our contractor and started working with it. But this does not mean that we have since taken their word for it. The quality of translations is regularly checked:

• our staff who understand the relevant languages
• translators of the contractor himself. The fact is that some translate there, and others read it at our request.

Surely you will say that you need to check the work of one company with specialists of another. But the fact is that localization companies are desperately fighting for customers. And if we send the texts to someone and ask them to evaluate, we will immediately be told what has been translated badly, let us do much better. Actually, attempts to lure us do not stop until now.

Sometimes, when a big release comes out, it is not always possible to check the documentation, localized shortly before the deadline. Then it is at your own risk to let out as is. But in such cases, we work closely with support: if there are any jambs in the documentation that are receiving complaints from users, then we immediately turn to the translators and rework. Fortunately, this rarely happens.

Translation issues

In the process of working on translations there may be certain shoals. They all need to be carefully negotiated with the translation office so that they understand and this does not happen again.

1) Inattentive translator - if there is a variable in a gui phrase, an inattentive translator can skip a part of it. For example, you have a variable (% 1) s, and in the translation you get (% 1). As a result, the phrase will not look right.

2) The translator thought - we are all human, it happens that the translator translates something wrong, and something quite simple. For example, the phrase This file is not valid will be translated as "File not found."

3) Too careful translator - such a translator translates everything that he sees. Here it is necessary to explain that the ProductName variable should not be translated as “Product Name”, otherwise it breaks down and the product names are not substituted in the product. Or if it translates the .xml file with the documentation, then you do not need to translate the tags and, otherwise, then this xml is not imported into the database because of the broken tags.

4) Difficult technical term or abbreviation - if there is something similar in the text to be translated, it is better to immediately direct the translators' attention to it in the comments, describe what it is and advise google to find out how it translates correctly into their language. Otherwise, you can get something far from the desired term.

5) Jambs due to the lack of comments - if you do not make comments for translators, they can ask questions not on all incomprehensible points. As a result, the quality of translations may suffer. , Parallels Access, iOS Android . , . Access . , , «», «».

6) – , . – . . , . . , Unable to save the license file. , , - Parallels Desktop. – « Parallels Desktop.» , « », .

7) – , , – . – , , «...», .

8) – , – 3 , . – , . – 3-4 .

9) – . , – , . - , – , , . .

10) – – . — . . , - , . . , . , Ctrl+Alt+Delete. , . , — Delete. , , , Ctrl+Alt+Delete Delete, : Delete, Ctrl+Alt+< >. , Delete . Ctrl+Alt+. . . Parallels Access, “Welcome to Parallels Access”. , . , : Welcome, to Parallels Access. . , , . , . « Parallels Access» «Parallels Access ». .

11) – - , . , « - ». – “Your grace period expires in %1 days.” , . , – « 5 /3 /1 ». ( , , – «.», – «.», – «.») ( “Days left until the grace period expires: %1.”. - , , (, (5), (3) , (1)), , .

, - , .
– , , . , .

:
, . , , , . , , , 12 .

:
. , , . , . , , , - , 12 – .

:
. , , . , , . , .

:
. , , 12. .

, , , – . -. , , , . , . .

ZY !