April 15, 2011 at 11:41Tips for preparing user help for software in English
Hello! Today we open a blog on Habré. Our specialization is translations into English, writing and sending out press releases on RuNet , as well as creating help systems for software. Over the years, some knowledge has accumulated that we want to share with you. I hope you find the blog useful. I wish you a pleasant reading and I am waiting for you as a regular visitor.
We start with a post on creating user manuals for software in English. User Help is an important component of a software product. Creating a certificate requires special care, as Errors and incomprehensible wording in it are often perceived as a defect in the program itself and spoil the impression of the product. Journalists mention poorly written or translated help as a lack of reviews, and users vote in rubles - if they have difficulty or do not understand the instructions in the manual, then they are unlikely to register a trial. On the other hand, a program with well-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 those rules that you are already guided by.
So, what kind of errors are often found in user help?
1. Irrational description of the procedure
In the description of the procedure, information must be located in the most rational way from the point of view of its perception by the user. This means that first you tell where the user should perform the action, and only then what he should do (click, open, select).
For example:
Wrong: Select Open from the File menu.
Correct: In the File menu, select Open.
2. Recording a multi-step procedure in one sentence. A
help author often tries to describe a complex procedure in one sentence. In order for the description to be clear and clear, it is necessary to break the long sentence into steps.
For example:
Wrong:
To select the type of the Distributor, click the Create button, and the floating window will open.
Correct:
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. Incorrect definition of steps
A complex procedure consists of several steps. Each step should contain an action and its result. However, descriptions are often found 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
Correct:
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 buttons in quotation marks
In user help, the name of the button is often quoted. However, many consider this a relic of the past, when typewriters had no other way to format text than quotation marks 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 name of the button: the name of the button 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 re-read the sentence again. Instead of "and / or" use "... or ... or both".
For example:
Wrong: You can convert a file to AVI and / or MP3.
Correct: You can convert a file to AVI or MP3, or both.
6. Misuse of terms An
inexperienced author often makes mistakes in the use of terms.
For example:
Wrong: Press the New icon to create a new project.
Right: Click the New 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 a program window with a mouse click.
7. Future tense
Often there are descriptions in which the response of the program to the user’s action is transmitted in the future tense. For example, "When you click the OK button, the program will start the conversion." This is not entirely correct. The future tense forces the reader to ask unnecessary questions: “When will the conversion begin?”, “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 expression of will. Sometimes “willan” was used when people talked about their plans for the future, because in the Old English language there was no special form for conveying the future. Over time, “willan” has become “will,” but it still retains an additional connotation of will. For example, the meaning of the expression of will is traced in the phrase “The pen won't write” (Russian - “The pen does not want to write”).
So, when we read the sentence “When you click the OK button, the program will start the conversion”, the verb “will” expresses not only the future, but also its modal meaning of expression of will. It turns out - the program "wants" to start the conversion. And if he doesn’t “want?” Use the present tense to avoid ambiguity in the description of the procedure.
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 user help style 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
User help should avoid abbreviations and acronyms.
For example:
Wrong: approx.
Correct: approximately
Incorrect: eg
Correct: for example
An exception can only be “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 at the first mention in the text the full name and abbreviation should be written in brackets. Further in the text use the abbreviation.
For example:
Correct:
Oxygen Software today introduces an enhanced version of its Oxygen Phone Manager II (OPM II) for Nokia and Vertu phones. The biggest change in OPM II is tested quality support for groundbreaking Series 40 5th Edition of Nokia phones, whose posh look and cool features have won the hearts of millions of people.
When writing help, you must strive for clarity, accuracy and conciseness. We hope that our recommendations will be useful to you in creating your user guide.
We start with a post on creating user manuals for software in English. User Help is an important component of a software product. Creating a certificate requires special care, as Errors and incomprehensible wording in it are often perceived as a defect in the program itself and spoil the impression of the product. Journalists mention poorly written or translated help as a lack of reviews, and users vote in rubles - if they have difficulty or do not understand the instructions in the manual, then they are unlikely to register a trial. On the other hand, a program with well-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 those rules that you are already guided by.
So, what kind of errors are often found in user help?
1. Irrational description of the procedure
In the description of the procedure, information must be located in the most rational way from the point of view of its perception by the user. This means that first you tell where the user should perform the action, and only then what he should do (click, open, select).
For example:
Wrong: Select Open from the File menu.
Correct: In the File menu, select Open.
2. Recording a multi-step procedure in one sentence. A
help author often tries to describe a complex procedure in one sentence. In order for the description to be clear and clear, it is necessary to break the long sentence into steps.
For example:
Wrong:
To select the type of the Distributor, click the Create button, and the floating window will open.
Correct:
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. Incorrect definition of steps
A complex procedure consists of several steps. Each step should contain an action and its result. However, descriptions are often found 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
Correct:
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 buttons in quotation marks
In user help, the name of the button is often quoted. However, many consider this a relic of the past, when typewriters had no other way to format text than quotation marks 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 name of the button: the name of the button 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 re-read the sentence again. Instead of "and / or" use "... or ... or both".
For example:
Wrong: You can convert a file to AVI and / or MP3.
Correct: You can convert a file to AVI or MP3, or both.
6. Misuse of terms An
inexperienced author often makes mistakes in the use of terms.
For example:
Wrong: Press the New icon to create a new project.
Right: Click the New 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 a program window with a mouse click.
7. Future tense
Often there are descriptions in which the response of the program to the user’s action is transmitted in the future tense. For example, "When you click the OK button, the program will start the conversion." This is not entirely correct. The future tense forces the reader to ask unnecessary questions: “When will the conversion begin?”, “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 expression of will. Sometimes “willan” was used when people talked about their plans for the future, because in the Old English language there was no special form for conveying the future. Over time, “willan” has become “will,” but it still retains an additional connotation of will. For example, the meaning of the expression of will is traced in the phrase “The pen won't write” (Russian - “The pen does not want to write”).
So, when we read the sentence “When you click the OK button, the program will start the conversion”, the verb “will” expresses not only the future, but also its modal meaning of expression of will. It turns out - the program "wants" to start the conversion. And if he doesn’t “want?” Use the present tense to avoid ambiguity in the description of the procedure.
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 user help style 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
User help should avoid abbreviations and acronyms.
For example:
Wrong: approx.
Correct: approximately
Incorrect: eg
Correct: for example
An exception can only be “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 at the first mention in the text the full name and abbreviation should be written in brackets. Further in the text use the abbreviation.
For example:
Correct:
Oxygen Software today introduces an enhanced version of its Oxygen Phone Manager II (OPM II) for Nokia and Vertu phones. The biggest change in OPM II is tested quality support for groundbreaking Series 40 5th Edition of Nokia phones, whose posh look and cool features have won the hearts of millions of people.
When writing help, you must strive for clarity, accuracy and conciseness. We hope that our recommendations will be useful to you in creating your user guide.