How to make text easier

In the last article, I promised that I will tell you how to make documents easier to read. There are two main areas: text and document structure. Today we will work with the texts. Technical documents in Russian are especially difficult to read, and more difficult to achieve lightness in them than in English. How can you fix wordy, bulky documents? Let’s try to make them more specific, simpler, shorter, and more consistent.

More specifically

Papers should be written for a specific target audience with a specific purpose. So that the intended user reads, understands, and does what he wanted according to the instructions.

The target audience seems to be some kind of external factor that does not affect the documents, but it is not. A lot of problems at the docks are solved precisely by referring to the target audience. For example, how clear is this text? We cannot say for everyone: for example, I understand it, but he does not really. We won’t get very far this way, we need some kind of solution. Namely: is it clear for the target audience? Let’s look at an example.

I wrote documents for Acronis Cyber ​​Infrastructure, this is when a cluster is made of servers, and it is used for storage and virtual machines. To put it simply, this product is designed for enterprises, in particular for service providers. The target audience of documents is system administrators, and not the simplest ones. They will be incomprehensible to an ordinary person. But this is not a bug, it is by design. If we were writing these docks for ordinary users, then:

  1. It would be necessary to explain all storage and HCI concepts in great detail and clearly. Such a dummy guide for dummies.
  2. It would be impossible to use the generally accepted terms of the sphere, it would be necessary to simplify and describe. For example, instead of “node” it might have been “server”, because this word is more common and clearer to everyone, although it does not convey the role of the server in the cluster.

In short, these would be completely different documents.

It’s bad when the target audience is not defined for the docks. Throwing begins: is that clear enough? Isn’t that too elementary? On the issue of GOSTs and ESPD. There, the target audience is often people who hardly know how to use a computer. Now there are few of them. Therefore, a document for an ordinary modern user, written according to the ESPD, can turn out to be very heavy, overloaded with unnecessary details. But, probably, at the time of writing the GOSTs, it would clearly fall into Central Asia.

Marginal notes

  • It is nice to have a section at the beginning of the document Target audienceso that it is immediately clear for whom the document was written. Unfortunately, it often says: “For everyone who reads this document or uses our product.” If you come across a normal section where the target audience is clearly described, please throw it off in the comments, I will read it with pleasure.
  • Sometimes the document is designed for a more or less general audience, but there are a couple of difficult points for experts, for example, some tricky settings. Such things can be removed in the knowledge base.
  • Even if you write a dock for admins and immediately indicate this in the section Target audience, all the same people will come who do not rummage at all. And they will write to you: “What is this? And this? Why is it so difficult? ” Be ready.

Easier

The tradition of Russian design texts is to explain in great detail what is already familiar and understandable to an ordinary user for a long time. I recommend removing redundant terms and explanations, such as “executable file” in the first example or “the flag for creating a shortcut on the desktop can be used to launch software for execution” in the second.

It was

To install the program, you must run the executable file “wizard.exe” and follow the instructions of the installation wizard.

Has become

To start the installation wizard, double click on the “wizard.exe” file.

It was

In this window, you can set a flag to create an icon (shortcut) on the desktop, which can be used to launch the software for execution. After setting the value of the flag, press the “Next” button.

Has become

Select the Create Desktop Icon check box if necessary. Click “Next”

Marginal notes

  • Quite calmly, you can remove from the docks the description of the general properties of GUI elements. That is, if you are describing a table, and in it (wow!) You can change the width of the columns by dragging the border, it is not necessary to write this. Real example: The size of the window parts and the width of the columns can be changed by moving the dividing bars with the left mouse button. The window position can be changed by moving the title bar using the left mouse button (LMB)
  • Sometimes the source code is so confusing that you don’t even know which side to approach. The most difficult thing here is to understand what is meant, and with understanding it will be easier to find simple words. Usually, such texts just need to be rewritten clean. Here’s an example: The user can change the position of the object manually by dragging it with the LMB to a convenient position. There are two ways to change the position of an object. The first method is free movement, when you can choose any position to install the object. 2nd method, when the position has a fixed place with a discrete angle of 45º and a fixed distance from the point of intersection of the graph with the viewfinder.

Shorter

Recently, at one of the webinars, I heard a very precise phrase: “Every word that you write, the user does not want to read.” I agree 100%. But at the same time, I confess, I know the feeling when I want to finish writing, and explain a little more, and repeat the same in other words, well, so that it will definitely come to you! I struggle with this feeling, and I advise you.

Making the text shorter is not exactly the same as making it easier. When we simplify the text, we remove unnecessary technical details. And when we shorten it, we remove figures of speech and unnecessary ordinary words. For example, if point 2 comes after point 1, you do not need to write “After completing point 1”. Or instead of “should be clicked” it is better to write “click”.

It was

After performing the indicated actions in the “P” mode, to print a ticket with one of the programmed tariffs from 1 to 9, it is enough to press the corresponding number key. The ticket will be automatically printed.

Has become

To print a ticket with a programmed fare from 1 to 9, click on the corresponding number.

Often in Russian instructions, you come across long paragraphs of solid text that need to be split into several paragraphs and shortened. Let’s look at the big paragraph where the instruction is hidden. A procedure for several steps in continuous text, also with a violation of the logical order, is a pain. But everything is fixable. We break it down into steps, organize it according to logic – and voila!

It was

To update, you need to temporarily copy the file “F” to the computer with the software, update the program “P” (specify the path to the file “F”), then copy the file back to the network resource. Before starting the update, you need to make sure there is enough free space on the disk where the “F” file is located – this is necessary to create a backup copy. The amount of free space must be at least the size of the updated file. If there is not enough free space, the program will display a corresponding message.

Has become

Update

  1. Make sure there is enough space on the disk where the F file is located to create a backup.
  2. Copy the file “F” from the network storage to the computer with the program “P”
  3. In the program “P” specify the path to the file “F” and update it.
  4. Copy the updated “F” file back to your NAS.

Marginal notes

  • When we are working with large paragraphs of solid text, we need to remember about visual effectiveness. Too many letters in a row – and it’s hard to read. Sometimes it is enough to break it down into steps or paragraphs, and sometimes you can think of a diagram. A sensible diagram decides. But in order to make a sensible scheme, you need to understand the essence of the procedure inside and out. This is where the developer’s help or program manager can come in handy.

More consistent

A technical writer is a creative person, so there can be many names for the same operation: “click”, “click”, “click”, and all in one document. And let’s multiply this by the number of creative people working on one document. I am for consistency. The same operation must be named the same. If you like Click, then write everywhere. If “Press” – the same. Pick an appropriate term and use it consistently everywhere. Better yet, start a corporate glossary, at least in Russian, and write down the necessary phrases there. +500 to consistency, and also helps beginners to get up to speed faster.

Marginal notes

  • Sometimes the correct name of something in Russian is not clear, but its English name is known. For example, we have a “node”, from the English “node”. How to find the correct Russian word? You can go to Microsoft glossary… There we select the English source language and the Russian language of translation, enter the word in English, and look at the proposed options in Russian. We get the “node”.
  • If you already decided to make the documents more consistent, these edits should be applied everywhere. Otherwise what’s the point? Typically, these changes affect most of the texts. Therefore, here you need to correctly calculate the timing and costs. And it’s especially important not to forget about localization, because for them this means a very large-scale change in several languages ​​at once.
  • When there is disk or drive in the documents, this is not very good. But when it’s the same in the GUI, it’s really bad. Therefore, we look at the GUI especially carefully and remember all the options that will then need to be edited.

Resources

Before you start correcting documents, you can read different books to better understand what’s what.

  • “The Word Alive and Dead” by Nora Gal. Classic.
  • “Alive as Life” by Korney Chukovsky, head of “Office”. Classic.
  • “Write, shorten” by Maxim Ilyakhov. A fresh look at old problems + a very practical approach. Here is a detailed description of how the texts can be shortened.
  • Developing Quality Technical Information: A Handbook for Writers and Editors from Gretchen Hargis et al. There is a lot about goals, objectives, target audience documents. And also good examples and practical advice.

PS. A separate topic is why English is so short, clear, and comprehensible compared to Russian. Although, for example, Spanish is also so-so in its ease, no better than ours. But this is already linguistics. While we will not go there, if necessary, write in the comments.

Similar Posts

Leave a Reply