How to improve the quality of the information system using the user manual
In fact, everything is completely different than it really is.
Antoine de Saint-Exupery
Much of the development of the user manual is regulated and described by state standards. But when creating large heterogeneous systems, there may be issues that are not fully covered by these documents.
The attitude to the user manual is different. Many do not at all wonder what the place and role of the document is in the process of developing large heterogeneous information systems; for others, everything is clear. Do not hurry. In this article, we will look at approaches to organizing the process of creating and maintaining this important document, assess the significance of the user's manual for the entire information system as a whole, and come to some unexpected conclusions.
')
The article will be useful for testers, technical writers, analysts, and even for project managers.
Some time ago, as an analyst, I began work on a project to develop a federal-scale information system. For quick immersion in the subject area, I was asked to take up the user manual: conduct an audit and organize the process of finalizing the document under the rapidly expanding functionality of the system.
I will separately dwell on the features of the project, since the approaches and principles to be discussed are developed and adapted specifically for the following conditions.
1. Scale.
Large heterogeneous distributed information system, which includes dozens of interacting subsystems.
2. Parallel development .
Because of the scale of the system, isolated teams of analysts, developers and testers are working on it.
3. Frequent changes .
Again, the consequence of scale is a constant stream of changes and improvements.
4. A relatively universal and standardized set of business processes within the project.
Most processes have a constant part similar to other business processes.
Even a superficial glance at the current version of the user's manual allowed us to conclude that the quality of the document was not high. There were two main problems: irrelevance and lack of uniformity in describing similar functions and processes .
Poor quality user guides can lead to a number of negative consequences for the entire project. I will highlight the main ones:
It was necessary to urgently correct the situation. And do it with minimal cost.
An individual approach was developed for each problem. Consider each problem and each approach in more detail.
The irrelevance of the document contains two classes of problems: an outdated description of the existing functionality and the absence of a description of the new system features. Algorithm to fix the problem was chosen as follows.
For convenience, the data were entered in a table (see Figure 1), in the rows of which automated processes and functions were indicated, and in the columns - the existing descriptions from the user's manual. The latter were additionally grouped into blocks for each subsystem. The result was a clear picture of the correspondence of processes / functions and their descriptions. In addition, it was possible to identify similar descriptions for further grouping.
After that, all descriptions were cataloged (an actual problem, since the total number of descriptions exceeded 100 pcs.). If the process was described in the user's manual, then the cell at the intersection of the corresponding row and column was put down the number of the item (section).
Further, the visual indicator "Traffic Light" was marked by the results of the comparison:
The use of color indicators made it possible to reveal the general picture: the user's manual needs to be edited ... and significantly.
Picture 1
Work has begun on the document. At this stage, again, the table has helped: if a process is edited in one block, then in another it is created in a similar percent by 80 ways.
The total number of descriptions of functions in the user manual is more than a hundred, typical - 25.
Further processing of descriptions required additional gradation: bright green - for scenarios in which everything is good and no changes are required; light green - for scenarios that are generally described correctly and only need to be fixed; orange - for those who are fundamentally incorrectly described and which must be corrected first.
Figure 2
As a result, the overall picture appeared in color: the vast orange spots of the problem areas were visible, a lot of light green and the almost absence of bright green.
The correspondence table during the work on the document:
Figure 3
Upon completion of the “painting” works, the following priorities were identified:
At this point, it is important to recall the Pareto law (principle 20/80): we corrected the most problematic orange areas relatively quickly and worked for a long time on light green ones. Indeed, in them, in fact, the whole point, if we strive to ensure that the user can really work with the manual.
In solving this problem, the task was to ensure uniformity in describing similar processes (cases) and significantly reduce the labor costs for updating and maintaining the document. An approach was chosen, according to which the description of each process is presented in the form of a building block (1), and the document itself - their combinations (3). All building blocks should be located in the repository (Wiki) with mandatory change control and versioning support (2).
Figure 4
The main advantage of this approach is a significant reduction in labor costs: when creating and editing the general part of the building block, the edits are made only once. Building the user manual from building blocks is also much faster than the traditional option.
A fundamentally important point: access to the repository should be provided to all teams working on the project, in accordance with the established regulations for its use.
Using this approach for updating and the method of “building blocks” for assembly, the document was managed to be brought into proper condition in a short time. Labor costs were reduced by more than 30%, compared with the traditional method of forming a document. It would seem that at this place it would be possible to designate a happy end, but I would like to continue. It will be interesting.
A quality user manual received new functions, perfectly integrated into the requirements management system and the overall development cycle (regardless of whether it is consistent or iterative) of the information system.
In the classical development cycle from requirements analysis (1) to testing (4), the stage of preparing documents is added, among which a user manual occupies a special place. Why is this document so important? For several reasons. In the case of parallel independent development of individual subsystems, loss of unification is possible (for example, the location of control elements, names, etc.). It is during the preparation of the user manual that inconsistencies / inconsistencies are visible, both in the functional plane and at the level of user interfaces.
Figure 5
Only at the user manual level, the system is visible in its entirety, and not as a collection of individual subsystems. The concept of building blocks allows you to solve the problem of inconsistencies, but only in the case of using the repository in the development of the staged part as reference materials. Thus, the manual has a new category of users - analysts and testers. And, of course, the document must be synchronized and fully comply with user requirements. At this stage, additional verification is carried out for compliance of user requirements with the developed functions (the user's manual, in fact, contains the business description of the system).
Figure 5 clearly shows that the development process is finalized by the creation of the manual. This document is also actively used at other stages of development.
Figure 6
A qualitatively and competently written manual that contains the actual description of automated functions becomes an important and relevant document from end users and developers and acquires some new functions:
Using the described approaches in the formation of the user manual allows you to:
I hope that after reading this article, some of you will have a new look at this seemingly simple, but as it turned out, a very important document and will adopt the considered approaches to its formation.
PS The article does not include questions of the content of the elements and sections of the user manual. This is considered in detail and regulated by subsection 3.4 of RD 50-34.698-9 and IEEE 1063-2001.
The structure and content of the documents Operator's Guide, Programmer's Guide, System Programmer's Guide are regulated by GOST 19.505-79, GOST 19.504-79 and GOST 19.503-79 respectively.
A generalized user guide structure, based on an analysis of the listed standards, is provided here. General methodology can be found in this article .
Antoine de Saint-Exupery
Much of the development of the user manual is regulated and described by state standards. But when creating large heterogeneous systems, there may be issues that are not fully covered by these documents.
The attitude to the user manual is different. Many do not at all wonder what the place and role of the document is in the process of developing large heterogeneous information systems; for others, everything is clear. Do not hurry. In this article, we will look at approaches to organizing the process of creating and maintaining this important document, assess the significance of the user's manual for the entire information system as a whole, and come to some unexpected conclusions.
')
The article will be useful for testers, technical writers, analysts, and even for project managers.
Description of the problem
Some time ago, as an analyst, I began work on a project to develop a federal-scale information system. For quick immersion in the subject area, I was asked to take up the user manual: conduct an audit and organize the process of finalizing the document under the rapidly expanding functionality of the system.
I will separately dwell on the features of the project, since the approaches and principles to be discussed are developed and adapted specifically for the following conditions.
1. Scale.
Large heterogeneous distributed information system, which includes dozens of interacting subsystems.
2. Parallel development .
Because of the scale of the system, isolated teams of analysts, developers and testers are working on it.
3. Frequent changes .
Again, the consequence of scale is a constant stream of changes and improvements.
4. A relatively universal and standardized set of business processes within the project.
Most processes have a constant part similar to other business processes.
Even a superficial glance at the current version of the user's manual allowed us to conclude that the quality of the document was not high. There were two main problems: irrelevance and lack of uniformity in describing similar functions and processes .
Poor quality user guides can lead to a number of negative consequences for the entire project. I will highlight the main ones:
- increased operating costs due to improper use of the system and, consequently, an increase in the load on the support service;
- user and customer dissatisfaction;
- increasing the cost of developing and maintaining the system.
It was necessary to urgently correct the situation. And do it with minimal cost.
Finding a solution
An individual approach was developed for each problem. Consider each problem and each approach in more detail.
Irrelevance of the document
The irrelevance of the document contains two classes of problems: an outdated description of the existing functionality and the absence of a description of the new system features. Algorithm to fix the problem was chosen as follows.
- Create a description of the model “AS ​​IS” (that is, what we have now, what functions and business processes are described).
- Describe the TO BE model (leading analysts for each subsystem were involved as consultants).
- Compare “AS IS” and “TO BE” with the help of the “Traffic Light” indicator and draw up an action plan.
For convenience, the data were entered in a table (see Figure 1), in the rows of which automated processes and functions were indicated, and in the columns - the existing descriptions from the user's manual. The latter were additionally grouped into blocks for each subsystem. The result was a clear picture of the correspondence of processes / functions and their descriptions. In addition, it was possible to identify similar descriptions for further grouping.
After that, all descriptions were cataloged (an actual problem, since the total number of descriptions exceeded 100 pcs.). If the process was described in the user's manual, then the cell at the intersection of the corresponding row and column was put down the number of the item (section).
Further, the visual indicator "Traffic Light" was marked by the results of the comparison:
- Green is a process in leadership and is needed in business.
- Red - the process is there, but not needed (delete!).
- Yellow - no process, but need (add!).
- Gray - the process is missing and not needed.
The use of color indicators made it possible to reveal the general picture: the user's manual needs to be edited ... and significantly.
Picture 1
Work has begun on the document. At this stage, again, the table has helped: if a process is edited in one block, then in another it is created in a similar percent by 80 ways.
The total number of descriptions of functions in the user manual is more than a hundred, typical - 25.
Further processing of descriptions required additional gradation: bright green - for scenarios in which everything is good and no changes are required; light green - for scenarios that are generally described correctly and only need to be fixed; orange - for those who are fundamentally incorrectly described and which must be corrected first.
Figure 2
As a result, the overall picture appeared in color: the vast orange spots of the problem areas were visible, a lot of light green and the almost absence of bright green.
The correspondence table during the work on the document:
Figure 3
Upon completion of the “painting” works, the following priorities were identified:
- remove the orange color - everything should be described correctly;
- make light green fields bright green.
At this point, it is important to recall the Pareto law (principle 20/80): we corrected the most problematic orange areas relatively quickly and worked for a long time on light green ones. Indeed, in them, in fact, the whole point, if we strive to ensure that the user can really work with the manual.
Lack of uniformity
In solving this problem, the task was to ensure uniformity in describing similar processes (cases) and significantly reduce the labor costs for updating and maintaining the document. An approach was chosen, according to which the description of each process is presented in the form of a building block (1), and the document itself - their combinations (3). All building blocks should be located in the repository (Wiki) with mandatory change control and versioning support (2).
Figure 4
The main advantage of this approach is a significant reduction in labor costs: when creating and editing the general part of the building block, the edits are made only once. Building the user manual from building blocks is also much faster than the traditional option.
A fundamentally important point: access to the repository should be provided to all teams working on the project, in accordance with the established regulations for its use.
Using this approach for updating and the method of “building blocks” for assembly, the document was managed to be brought into proper condition in a short time. Labor costs were reduced by more than 30%, compared with the traditional method of forming a document. It would seem that at this place it would be possible to designate a happy end, but I would like to continue. It will be interesting.
Place the user guide in the requirements management cycle
A quality user manual received new functions, perfectly integrated into the requirements management system and the overall development cycle (regardless of whether it is consistent or iterative) of the information system.
In the classical development cycle from requirements analysis (1) to testing (4), the stage of preparing documents is added, among which a user manual occupies a special place. Why is this document so important? For several reasons. In the case of parallel independent development of individual subsystems, loss of unification is possible (for example, the location of control elements, names, etc.). It is during the preparation of the user manual that inconsistencies / inconsistencies are visible, both in the functional plane and at the level of user interfaces.
Figure 5
Only at the user manual level, the system is visible in its entirety, and not as a collection of individual subsystems. The concept of building blocks allows you to solve the problem of inconsistencies, but only in the case of using the repository in the development of the staged part as reference materials. Thus, the manual has a new category of users - analysts and testers. And, of course, the document must be synchronized and fully comply with user requirements. At this stage, additional verification is carried out for compliance of user requirements with the developed functions (the user's manual, in fact, contains the business description of the system).
Figure 5 clearly shows that the development process is finalized by the creation of the manual. This document is also actively used at other stages of development.
Figure 6
findings
A qualitatively and competently written manual that contains the actual description of automated functions becomes an important and relevant document from end users and developers and acquires some new functions:
- knowledge base component;
- additional line of testing and verification of functions, instrument of control;
- means of general improvement of the quality of an information system.
Using the described approaches in the formation of the user manual allows you to:
- significantly reduce the cost of creating the document and keeping it up to date;
- automate the process of forming a document;
- deeply integrate and synchronize the process of preparing the user's manual with the other processes of developing an information system;
- improve the quality of the information system as a whole.
I hope that after reading this article, some of you will have a new look at this seemingly simple, but as it turned out, a very important document and will adopt the considered approaches to its formation.
PS The article does not include questions of the content of the elements and sections of the user manual. This is considered in detail and regulated by subsection 3.4 of RD 50-34.698-9 and IEEE 1063-2001.
The structure and content of the documents Operator's Guide, Programmer's Guide, System Programmer's Guide are regulated by GOST 19.505-79, GOST 19.504-79 and GOST 19.503-79 respectively.
A generalized user guide structure, based on an analysis of the listed standards, is provided here. General methodology can be found in this article .
Source: https://habr.com/ru/post/329358/
All Articles