Testing of software documentation
Once in ancient times, I had the task of testing documentation for several software products. Using Google, it was not possible to find for once or twice the information about what qualities documentation should possess and who needs it. Collected all bit by bit. It has long been decided to write about it, and here, taking advantage of the presence of holidays, I publish.
The most important quality, which must have documentation. Scenarios should be described exactly, their implementation should lead to the achievement of the goals for which the product was created. If there are alternative scenarios, then they should be mentioned.
The obvious point implies that each element of the functional, whether it is an interface element, such as a button, a checkbox, a tooltip, etc. or the command to be entered, or the response to the actions must be described. Including it should be borne in mind that the user may need to find in the documentation of the algorithm of action when a certain message appears.
There should not be such that any mandatory and important user actions are mentioned in passing, you need to pay attention to the description of all necessary actions. Documentation should not resemble a loan agreement, in which all additional conditions are described in small print. For example, it is necessary to explicitly prescribe the information that if a comma instead of a dot is in the configuration file, the application will not start. Just as in a credit agreement it is worthwhile to prescribe in a prominent place that the interest rate will be 300% per annum instead of 20% in case of non-payment of the payment on time.
')
If you are testing the documentation for a software product that has many versions, then you should pay attention to the relevance of the description. It may be that in the current version the functionality has been changed, but it did not get into the documentation. Or at the last moment it was decided not to include the feature in the current release, and it is already described in the documentation. Also pay attention to the relevance of the years, contact details, system requirements, license agreement, screenshots.
Important quality. It rarely happens that documentation is read slowly at leisure. Most often, people turn to documentation when something doesn’t work for them, it’s likely that the user is reading the documentation during off-hours. Here you can recommend to minimize the number of chains of actions with dependencies. The execution of the script should not resemble the passage of the quest. It would be good if all the necessary conditions for the execution of the script were described before the scenario. You can make this analogy: If you want to nail a shelf to a brick wall, then in addition to the shelf, you will definitely need a puncher, a drill, a dowel-nails.
The emotional reaction when interacting with software products is very similar to the reaction when interacting with other people. If the user is reading the documentation because he has any problems, he will most likely be in an irritated state. Here we can recommend doing atomic sentences and paragraphs. For example, instead of << Reinstall the application if you encounter problems when using it. Problems arise when the operating system component-1 is installed, and condition-2 is set in the operating system settings. >> it is better to prescribe << If the operating system component-1 is installed and condition-2 is specified in the operating system settings, then the application may encounter problems which can be solved only by reinstalling. >>
The documentation should have a clear structure and the user should be able to quickly find information on the table of contents in it. You can draw a parallel with the quality of the camera: a simple camera should have such constructive characteristics so that you can quickly use it without losing moment. If the camera gets out of the case for a long time and turns on for a long time, then at the right time it may be useless. With reference to documentation and help, if it takes a lot of time to search for some information, then the user can stop searching because he lacks the patience to do things.
If any user actions are irreversible, then it is worth explicitly indicating this. For example, when you delete something in the program, then you can not always restore it. It is also worth adding information about how you can reverse these or other actions. For example, we want to add a lot of data to the program, but we are not sure that they are correct, we should clearly indicate the way in which our actions can be reversed, for example, restoring settings).
After describing the sequence of some actions, you should indicate the expected result. Just as it is worth trying the soup after adding salt and spices there.
It is worth adding to the documentation information about what will happen if the user does not perform the required actions from him. For example, if the user does not specify the ip-address of the network interface, then this interface will not be able to send packets.
The terminology most suitable for the objects to be tested should be used. If a specific term is used, then it is worth describing it separately. If a double interpretation of the term is possible, then it should be clarified which one is used.
The scenarios should indicate what actions are being done for what purpose. The meaning of the actions performed should be clear.
In some scenarios, the sequence of actions is important. For example, when cooking soup, we first pour water, and then add other ingredients, such as potatoes. If you first put the potatoes and pour the water much later, then instead of the soup you get something inedible.
Of course, the text must be described correctly. Spelling can be checked in MS Word or other means. To check the syntax and punctuation, it is necessary to read the text, understand its meaning, understand the meanings of each of the terms used.
If there are any settings, and they have default values, it would be good if this is described. The user wants to find information about the default settings, if he changed the settings, but did not remember the changes, and after that the program stopped working correctly.
If the product is designed for simple users, then the user's documentation should be described in simple, understandable terms. If the product is designed for Apple users or for Linux administrators, then you should take into account the features of these users. Manuals for server and management software are often targeted at system administrators.
More applicable to help, but often users need information about only one functional element. And there is no desire and ability to study fully the documentation. You should not force the user to study the product if there is a possibility not to do this. For example, if you need to change the font in a text editor, you should not indicate in the documentation that before doing this you need to study the history of text editors, study the list of functions of a text editor, study what fonts are, etc.
People do not always ask themselves how the program works; the result is important for them. And it should be borne in mind that the product can be used by different users. For example, a highly qualified system administrator may need to show the results of his work using the product to the director. A director can look into the documentation if the results shown are very important within his activities. Here it is worth as little as possible to use complex technical terms to understand which will have to open the Internet. A housewife does not need to know how a microwave oven functions, but it is important for her to know that it is possible to cook in it and not to put metal objects inside. Also, a housewife, unlike a scientist, should know that you should not put eggs in the microwave.
I often notice that few people pay attention to the quality of documentation. Indeed, to whom it brings benefits and what? I suspect that many teams in the development of software products create documentation only because the task of creating the documentation was set by the superiors. And lowering the priority of ensuring the quality of documentation is due to the fact that it is not possible to calculate in numbers the benefits that this gives. Unfortunately, I can not provide such statistics in numbers.
The benefit from the availability of documentation can be compared with the benefit of creating additional infrastructure for housing construction. On the one hand, the sale is dominated by the area of housing: the price is assigned per square. But if you look closely - the price in some houses is much higher than the price in others. And this is due primarily to the surrounding infrastructure (parking, elevators, lawns, etc.).
The availability of high-quality documentation gives advantages: users do not seek to abandon the product, the load on technical support decreases, there are fewer questions within the development team about how the product should function, and it is easier to sell it.
The list of qualities on which it is possible to be guided when testing documentation:
1. Script performance
The most important quality, which must have documentation. Scenarios should be described exactly, their implementation should lead to the achievement of the goals for which the product was created. If there are alternative scenarios, then they should be mentioned.
2. Completeness of the description
The obvious point implies that each element of the functional, whether it is an interface element, such as a button, a checkbox, a tooltip, etc. or the command to be entered, or the response to the actions must be described. Including it should be borne in mind that the user may need to find in the documentation of the algorithm of action when a certain message appears.
3. Attention to mandatory points
There should not be such that any mandatory and important user actions are mentioned in passing, you need to pay attention to the description of all necessary actions. Documentation should not resemble a loan agreement, in which all additional conditions are described in small print. For example, it is necessary to explicitly prescribe the information that if a comma instead of a dot is in the configuration file, the application will not start. Just as in a credit agreement it is worthwhile to prescribe in a prominent place that the interest rate will be 300% per annum instead of 20% in case of non-payment of the payment on time.
')
4. The relevance of the description
If you are testing the documentation for a software product that has many versions, then you should pay attention to the relevance of the description. It may be that in the current version the functionality has been changed, but it did not get into the documentation. Or at the last moment it was decided not to include the feature in the current release, and it is already described in the documentation. Also pay attention to the relevance of the years, contact details, system requirements, license agreement, screenshots.
5. Adaptation to the fact that the user will be in a hurry
Important quality. It rarely happens that documentation is read slowly at leisure. Most often, people turn to documentation when something doesn’t work for them, it’s likely that the user is reading the documentation during off-hours. Here you can recommend to minimize the number of chains of actions with dependencies. The execution of the script should not resemble the passage of the quest. It would be good if all the necessary conditions for the execution of the script were described before the scenario. You can make this analogy: If you want to nail a shelf to a brick wall, then in addition to the shelf, you will definitely need a puncher, a drill, a dowel-nails.
6. Adaptation to the fact that the user will be annoyed
The emotional reaction when interacting with software products is very similar to the reaction when interacting with other people. If the user is reading the documentation because he has any problems, he will most likely be in an irritated state. Here we can recommend doing atomic sentences and paragraphs. For example, instead of << Reinstall the application if you encounter problems when using it. Problems arise when the operating system component-1 is installed, and condition-2 is set in the operating system settings. >> it is better to prescribe << If the operating system component-1 is installed and condition-2 is specified in the operating system settings, then the application may encounter problems which can be solved only by reinstalling. >>
7. Structured, adaptability to quick search
The documentation should have a clear structure and the user should be able to quickly find information on the table of contents in it. You can draw a parallel with the quality of the camera: a simple camera should have such constructive characteristics so that you can quickly use it without losing moment. If the camera gets out of the case for a long time and turns on for a long time, then at the right time it may be useless. With reference to documentation and help, if it takes a lot of time to search for some information, then the user can stop searching because he lacks the patience to do things.
8. Indication of irreversibility of actions.
If any user actions are irreversible, then it is worth explicitly indicating this. For example, when you delete something in the program, then you can not always restore it. It is also worth adding information about how you can reverse these or other actions. For example, we want to add a lot of data to the program, but we are not sure that they are correct, we should clearly indicate the way in which our actions can be reversed, for example, restoring settings).
9. Confirmation of expected
After describing the sequence of some actions, you should indicate the expected result. Just as it is worth trying the soup after adding salt and spices there.
10. Description of the consequences of non-user actions
It is worth adding to the documentation information about what will happen if the user does not perform the required actions from him. For example, if the user does not specify the ip-address of the network interface, then this interface will not be able to send packets.
11. Clarity of information
The terminology most suitable for the objects to be tested should be used. If a specific term is used, then it is worth describing it separately. If a double interpretation of the term is possible, then it should be clarified which one is used.
12. Logic and consistency
The scenarios should indicate what actions are being done for what purpose. The meaning of the actions performed should be clear.
13. The sequence of presentation
In some scenarios, the sequence of actions is important. For example, when cooking soup, we first pour water, and then add other ingredients, such as potatoes. If you first put the potatoes and pour the water much later, then instead of the soup you get something inedible.
14. Spelling, syntax, punctuation
Of course, the text must be described correctly. Spelling can be checked in MS Word or other means. To check the syntax and punctuation, it is necessary to read the text, understand its meaning, understand the meanings of each of the terms used.
15. Availability of default settings description
If there are any settings, and they have default values, it would be good if this is described. The user wants to find information about the default settings, if he changed the settings, but did not remember the changes, and after that the program stopped working correctly.
16. Adaptability to the audience
If the product is designed for simple users, then the user's documentation should be described in simple, understandable terms. If the product is designed for Apple users or for Linux administrators, then you should take into account the features of these users. Manuals for server and management software are often targeted at system administrators.
17. Atomicity of scenarios
More applicable to help, but often users need information about only one functional element. And there is no desire and ability to study fully the documentation. You should not force the user to study the product if there is a possibility not to do this. For example, if you need to change the font in a text editor, you should not indicate in the documentation that before doing this you need to study the history of text editors, study the list of functions of a text editor, study what fonts are, etc.
18. Adaptation to the least possible user skills
People do not always ask themselves how the program works; the result is important for them. And it should be borne in mind that the product can be used by different users. For example, a highly qualified system administrator may need to show the results of his work using the product to the director. A director can look into the documentation if the results shown are very important within his activities. Here it is worth as little as possible to use complex technical terms to understand which will have to open the Internet. A housewife does not need to know how a microwave oven functions, but it is important for her to know that it is possible to cook in it and not to put metal objects inside. Also, a housewife, unlike a scientist, should know that you should not put eggs in the microwave.
Who needs high-quality documentation
I often notice that few people pay attention to the quality of documentation. Indeed, to whom it brings benefits and what? I suspect that many teams in the development of software products create documentation only because the task of creating the documentation was set by the superiors. And lowering the priority of ensuring the quality of documentation is due to the fact that it is not possible to calculate in numbers the benefits that this gives. Unfortunately, I can not provide such statistics in numbers.
The benefit from the availability of documentation can be compared with the benefit of creating additional infrastructure for housing construction. On the one hand, the sale is dominated by the area of housing: the price is assigned per square. But if you look closely - the price in some houses is much higher than the price in others. And this is due primarily to the surrounding infrastructure (parking, elevators, lawns, etc.).
The availability of high-quality documentation gives advantages: users do not seek to abandon the product, the load on technical support decreases, there are fewer questions within the development team about how the product should function, and it is easier to sell it.
Source: https://habr.com/ru/post/346290/
All Articles