About the importance of documentation
Many of us work in companies with already established application software development processes, and a wide variety of documents are an integral part of these processes. However, there are companies in which there are no traditions and processes of writing technical documentation, and all the information is in the heads and in corporate e-mail. If you come from a company of the first type to a company of the second type, you very quickly find that working documentation is necessary as air. Why? Let's look at the main types of working documentation in software development, and try to imagine life without them.
1. Terms of Reference. TK is the link between business and development. This is the document in which business and programmers come to a common opinion on what should be implemented and how. If it is not customary in the company to write TZ, then no one will ever be able to understand what has already been implemented and what has not yet been done. This will inevitably lead to multiple duplication of functionality, as people change over time, administrative divisions change, functions are transferred from one department to another, and so on. In addition, it will be damn difficult to supplement the already implemented functionality with new features, because in order to understand (especially the new employee), what and how it was implemented, you will have to talk with dozens of employees and raise months of corporate correspondence.
2. HLA (high level architecture). This document describes at the architecture level how we will implement what is described in the ToR. He paints in what places it will be necessary to make changes, describes the essence of the changes, and this very document describes such a very important part as interfaces between modules / subsystems. If I am not mistaken, DeMarco and Lister were very right that it was the most "bad" (that is, difficult to find and eliminate) bugs that occur during interaction between systems, in interfaces. Since HLA is coordinated by development teams, then, in fact, this document is the one place where development teams agree on how their products will interact with each other. If you do not write these documents, you will never find someone who has misinterpreted the interface, which ultimately will lead to errors in the architecture, which in the future can be very costly. The quality of the code will drop dramatically, there will be a lot of hard-to-localize errors. In addition, in the future, in order to understand how the interaction between the two modules is arranged, the new person will again have to communicate with dozens of people and raise the months of correspondence.
3. LLD (low level decomposition). This is a document that is created inside the development team. It describes in detail all the necessary implementation methods and APIs. In fact, after writing this document, it remains only to encode the described. Without this document, programmers will not have a clear understanding of what needs to be done, which will further lead to an increase in the number of bugs (that is, a reduction in the quality of the code).
')
4. PMI (program and testing methodology). This is, perhaps, the main document from the field of testing, which describes step by step what needs to be done in order for a business to clearly decide that the implemented functionality works correctly and according to the TOR. Without such a document, you cannot check the functionality for errors (the discrepancy of the TK is also a bug), which ultimately greatly increases the risk that a bunch of bugs will come out on the production platform, up to the complete functional inoperability. In addition, without this document, the acceptance of the functional by the business turns into a non-formalized process with all the ensuing consequences such as unfounded claims to the development by the business.
5. User Guide. What the user needs to do to perform a certain business process using your software. Many screenshots, few words. Without this document, users will regularly for each sneeze to call in support and (in particularly neglected cases) in the development. Needless to say, a new employee without this document will find it extremely difficult to understand the application software of an enterprise, which, as a rule, is not distinguished by the ease and intuitiveness of the interface?
6. Guide system administrator. An extremely necessary document describing what resources an application software needs, how to set up this software and how to distribute privileges and rights in it. The document is used by both system administrators and technical support (this is not the same division everywhere). Without this document, your software risks being left without resources at the most crucial moment (CPU core, disk space). There will also be a lot of problems with the timeliness of distribution of rights: if the information is in the mind of two people, one is sick, the other is on vacation, then in order for an employee to receive the necessary privileges, he will have to wait a week. A week is a very long time for a business. For business, even an hour is too long.
It is clear that in this article far from all the documents accompanying the development process from the appearance of the need for something to the realization of this something in production are reviewed. I didn’t touch on the project management area at all, and in this area documentation is the basis of the basics. I have not described all the development and testing documents. But, I hope, I convinced you (are there really people who need to be convinced of this?) That technical documentation is an extremely necessary and useful thing, which should not be neglected in any way when developing software.
Write documents!
1. Terms of Reference. TK is the link between business and development. This is the document in which business and programmers come to a common opinion on what should be implemented and how. If it is not customary in the company to write TZ, then no one will ever be able to understand what has already been implemented and what has not yet been done. This will inevitably lead to multiple duplication of functionality, as people change over time, administrative divisions change, functions are transferred from one department to another, and so on. In addition, it will be damn difficult to supplement the already implemented functionality with new features, because in order to understand (especially the new employee), what and how it was implemented, you will have to talk with dozens of employees and raise months of corporate correspondence.
2. HLA (high level architecture). This document describes at the architecture level how we will implement what is described in the ToR. He paints in what places it will be necessary to make changes, describes the essence of the changes, and this very document describes such a very important part as interfaces between modules / subsystems. If I am not mistaken, DeMarco and Lister were very right that it was the most "bad" (that is, difficult to find and eliminate) bugs that occur during interaction between systems, in interfaces. Since HLA is coordinated by development teams, then, in fact, this document is the one place where development teams agree on how their products will interact with each other. If you do not write these documents, you will never find someone who has misinterpreted the interface, which ultimately will lead to errors in the architecture, which in the future can be very costly. The quality of the code will drop dramatically, there will be a lot of hard-to-localize errors. In addition, in the future, in order to understand how the interaction between the two modules is arranged, the new person will again have to communicate with dozens of people and raise the months of correspondence.
3. LLD (low level decomposition). This is a document that is created inside the development team. It describes in detail all the necessary implementation methods and APIs. In fact, after writing this document, it remains only to encode the described. Without this document, programmers will not have a clear understanding of what needs to be done, which will further lead to an increase in the number of bugs (that is, a reduction in the quality of the code).
')
4. PMI (program and testing methodology). This is, perhaps, the main document from the field of testing, which describes step by step what needs to be done in order for a business to clearly decide that the implemented functionality works correctly and according to the TOR. Without such a document, you cannot check the functionality for errors (the discrepancy of the TK is also a bug), which ultimately greatly increases the risk that a bunch of bugs will come out on the production platform, up to the complete functional inoperability. In addition, without this document, the acceptance of the functional by the business turns into a non-formalized process with all the ensuing consequences such as unfounded claims to the development by the business.
5. User Guide. What the user needs to do to perform a certain business process using your software. Many screenshots, few words. Without this document, users will regularly for each sneeze to call in support and (in particularly neglected cases) in the development. Needless to say, a new employee without this document will find it extremely difficult to understand the application software of an enterprise, which, as a rule, is not distinguished by the ease and intuitiveness of the interface?
6. Guide system administrator. An extremely necessary document describing what resources an application software needs, how to set up this software and how to distribute privileges and rights in it. The document is used by both system administrators and technical support (this is not the same division everywhere). Without this document, your software risks being left without resources at the most crucial moment (CPU core, disk space). There will also be a lot of problems with the timeliness of distribution of rights: if the information is in the mind of two people, one is sick, the other is on vacation, then in order for an employee to receive the necessary privileges, he will have to wait a week. A week is a very long time for a business. For business, even an hour is too long.
It is clear that in this article far from all the documents accompanying the development process from the appearance of the need for something to the realization of this something in production are reviewed. I didn’t touch on the project management area at all, and in this area documentation is the basis of the basics. I have not described all the development and testing documents. But, I hope, I convinced you (are there really people who need to be convinced of this?) That technical documentation is an extremely necessary and useful thing, which should not be neglected in any way when developing software.
Write documents!
Source: https://habr.com/ru/post/218089/
All Articles