Tips on how to prepare user help for software in English
Hello! Today we open a blog on Habré. Our specialization is translation into English, writing and sending press releases in RuNet , as well as creating reference systems for software. For several years of work have accumulated some knowledge that we want to share with you. I hope that the blog will be useful to you. I wish you a pleasant reading and I am waiting for you in regular visitors.
We start with a post about creating user manuals for software in English. User help is an important component of a software product. Creating a certificate requires special care, because errors and incomprehensible formulations in it are often perceived as a defect of the program itself and spoil the impression about the product. Journalists mention poorly written or translated help as a flaw in the reviews, and users vote with a ruble — if they have difficulty or do not understand the instructions in the manual at all, then they hardly register a trial. On the other hand, a program with quality translated help is easier to sell.
')
In this post I will describe some errors that are possible in the user's help in English, and how to avoid them. These recommendations are not exhaustive. It makes sense to use them together with the rules that you already follow.
So, what kind of errors are often found in the user's help?
1. Irrational description of the procedure
In the description of the procedure, information should be placed in the most rational way in terms of its perception by the user. This means that first you tell where the user should perform the action, and then what he should do (click, open, select).
For example:
Incorrect: Select Open from the File menu.
Correct: In the File menu, select Open.
2. Record a multi-step procedure in one sentence
The author of the help often tries to describe a complex procedure in one sentence. In order for the description to be clear and precise, it is necessary to break up the long sentence into steps.
For example:
Wrong:
Click the Create button and the floating window will open.
Right:
To select the distributor type, follow these steps:
1. Click the Create button.
2. On the Create window, select the distributor type.
3. Click OK to save the selection.
3. Wrong definition of steps
A complex procedure consists of several steps. Each step must contain an action and its result. However, there are often descriptions in which both the action and the result are presented as separate steps. It is not right.
For example:
Wrong:
1. Select the Phonebook tab.
2. The Phonebook window opens.
3. Click a contact.
4. The contact profile opens
Right:
1. Select the Phonebook tab.
The Phonebook window opens.
2. Click a contact.
The contact profile opens.
Or so:
1. Select the Phonebook tab.
2. On the Phonebook window, click a contact.
4. Name of the buttons in quotes
In the user's help, the name of the button is often quoted. However, many consider this to be a relic of the past, when typewriters had no other way of formatting text except quotes and underscores. It is best to write the name of the button in small capital letters or in bold.
For example:
Wrong: The “Remove” button removes a file from the list.
Correct: The REMOVE button removes a file from the list.
Correct: The Remove button removes a file from the list.
By the way, sometimes you can find the wrong word order in the spelling of the button name: the button name is written after the word “button”.
For example:
Wrong: The button New enters a new transaction.
Correct: The New button enters a new transaction.
5. And / Or
Do not use the "and / or" combination. It complicates the perception of the text, forcing the user to reread the sentence again. Instead of "and / or" use "... or ... or both".
For example:
Wrong: You can convert to AVI and / or MP3.
Correct: You can convert a file to AVI or MP3, or both.
6. Incorrect use of terms
An inexperienced author often makes mistakes in the use of terms.
For example:
Wrong: Press the icon to create a new project.
Correct: Click the icon to create a new project.
The verb “press” means pressing a key on the keyboard, and “click” means pressing a button or icon in the program window with a mouse click.
7. Future tense
Often there are descriptions in which the program’s response to a user’s action is transmitted in a future time. For example, "When you click the OK button, the program will start the conversion." This is not entirely correct. Future tense forces the reader to ask unnecessary questions: “When will the conversion start?”, “What if it does not start?” Why do they ask such questions? Very simple.
The verb “will”, which is now used to express the future tense, originally had the form “willan” and was a modal verb expressing desire or will. Sometimes “willan” was used when people talked about their plans for the future, because There was no special form in Old English to convey the future. Over time, “willan” turned into “will”, but so far it retains an additional tinge of will. For example, the meaning of a will expression can be traced in the phrase “The pen will not write” (Rus. - “The pen does not want to write”).
So, when we read the sentence “When you click the OK button, the verb“ will ”expresses not only the future, but also its modal meaning of will expression. It turns out - the program "wants" to start the conversion. And if you do not “want it?” To avoid ambiguity in the description of the procedure, use the present tense.
Wrong: When you click the OK button, the program will start the conversion.
Correct: When you click the OK button, the program starts the conversion.
8. Jargon
The style of user help should be neutral. The use of stylistically colored words distracts the user and is a stylistic error that should be avoided.
Wrong: Kill the app.
Correct: Close the application.
Wrong: Hit the Search button.
Correct: Click the Search button.
9. Abbreviations
In the user's help, you should avoid abbreviations and abbreviations.
For example:
Wrong: approx.
Correct: approximately
Wrong: eg
Correct: for example
The only exception is “etc.”
The name of several words should not be abbreviated if it is used in the text only once. However, if it is used several times, then when first mentioned in the text should write the full name and abbreviation in brackets. Further in the text use an abbreviation.
For example:
Right:
Oxygen Software today for Nokia and Vertu phones. This is a list of the 5th editions of Nokia phones, which has been chosen for the groundbreaking series.
When writing help, it is necessary to strive for clarity, accuracy and brevity. We hope that our recommendations will be useful to you when creating your user guide.
We start with a post about creating user manuals for software in English. User help is an important component of a software product. Creating a certificate requires special care, because errors and incomprehensible formulations in it are often perceived as a defect of the program itself and spoil the impression about the product. Journalists mention poorly written or translated help as a flaw in the reviews, and users vote with a ruble — if they have difficulty or do not understand the instructions in the manual at all, then they hardly register a trial. On the other hand, a program with quality translated help is easier to sell.
')
In this post I will describe some errors that are possible in the user's help in English, and how to avoid them. These recommendations are not exhaustive. It makes sense to use them together with the rules that you already follow.
So, what kind of errors are often found in the user's help?
1. Irrational description of the procedure
In the description of the procedure, information should be placed in the most rational way in terms of its perception by the user. This means that first you tell where the user should perform the action, and then what he should do (click, open, select).
For example:
Incorrect: Select Open from the File menu.
Correct: In the File menu, select Open.
2. Record a multi-step procedure in one sentence
The author of the help often tries to describe a complex procedure in one sentence. In order for the description to be clear and precise, it is necessary to break up the long sentence into steps.
For example:
Wrong:
Click the Create button and the floating window will open.
Right:
To select the distributor type, follow these steps:
1. Click the Create button.
2. On the Create window, select the distributor type.
3. Click OK to save the selection.
3. Wrong definition of steps
A complex procedure consists of several steps. Each step must contain an action and its result. However, there are often descriptions in which both the action and the result are presented as separate steps. It is not right.
For example:
Wrong:
1. Select the Phonebook tab.
2. The Phonebook window opens.
3. Click a contact.
4. The contact profile opens
Right:
1. Select the Phonebook tab.
The Phonebook window opens.
2. Click a contact.
The contact profile opens.
Or so:
1. Select the Phonebook tab.
2. On the Phonebook window, click a contact.
4. Name of the buttons in quotes
In the user's help, the name of the button is often quoted. However, many consider this to be a relic of the past, when typewriters had no other way of formatting text except quotes and underscores. It is best to write the name of the button in small capital letters or in bold.
For example:
Wrong: The “Remove” button removes a file from the list.
Correct: The REMOVE button removes a file from the list.
Correct: The Remove button removes a file from the list.
By the way, sometimes you can find the wrong word order in the spelling of the button name: the button name is written after the word “button”.
For example:
Wrong: The button New enters a new transaction.
Correct: The New button enters a new transaction.
5. And / Or
Do not use the "and / or" combination. It complicates the perception of the text, forcing the user to reread the sentence again. Instead of "and / or" use "... or ... or both".
For example:
Wrong: You can convert to AVI and / or MP3.
Correct: You can convert a file to AVI or MP3, or both.
6. Incorrect use of terms
An inexperienced author often makes mistakes in the use of terms.
For example:
Wrong: Press the icon to create a new project.
Correct: Click the icon to create a new project.
The verb “press” means pressing a key on the keyboard, and “click” means pressing a button or icon in the program window with a mouse click.
7. Future tense
Often there are descriptions in which the program’s response to a user’s action is transmitted in a future time. For example, "When you click the OK button, the program will start the conversion." This is not entirely correct. Future tense forces the reader to ask unnecessary questions: “When will the conversion start?”, “What if it does not start?” Why do they ask such questions? Very simple.
The verb “will”, which is now used to express the future tense, originally had the form “willan” and was a modal verb expressing desire or will. Sometimes “willan” was used when people talked about their plans for the future, because There was no special form in Old English to convey the future. Over time, “willan” turned into “will”, but so far it retains an additional tinge of will. For example, the meaning of a will expression can be traced in the phrase “The pen will not write” (Rus. - “The pen does not want to write”).
So, when we read the sentence “When you click the OK button, the verb“ will ”expresses not only the future, but also its modal meaning of will expression. It turns out - the program "wants" to start the conversion. And if you do not “want it?” To avoid ambiguity in the description of the procedure, use the present tense.
Wrong: When you click the OK button, the program will start the conversion.
Correct: When you click the OK button, the program starts the conversion.
8. Jargon
The style of user help should be neutral. The use of stylistically colored words distracts the user and is a stylistic error that should be avoided.
Wrong: Kill the app.
Correct: Close the application.
Wrong: Hit the Search button.
Correct: Click the Search button.
9. Abbreviations
In the user's help, you should avoid abbreviations and abbreviations.
For example:
Wrong: approx.
Correct: approximately
Wrong: eg
Correct: for example
The only exception is “etc.”
The name of several words should not be abbreviated if it is used in the text only once. However, if it is used several times, then when first mentioned in the text should write the full name and abbreviation in brackets. Further in the text use an abbreviation.
For example:
Right:
Oxygen Software today for Nokia and Vertu phones. This is a list of the 5th editions of Nokia phones, which has been chosen for the groundbreaking series.
When writing help, it is necessary to strive for clarity, accuracy and brevity. We hope that our recommendations will be useful to you when creating your user guide.
Source: https://habr.com/ru/post/117540/
All Articles