Copyright Notice
- The original author of this article: Brother Gu’s younger brother
- Author blog address: http://blog.csdn.net/lfdfhl
- Reference materials for this article: "Software Documentation Writing Tutorial" by Electronic Industry Press, edited by Ma Ping and Huang Dongmei
Development Document Classification Overview
Documents can be divided into the following categories according to different functions and functions during the implementation of software projects:
- Feasibility Study Report
- The project proposal
- Bidding documents
- needs analysis book
- Outline design book
- detailed design book
- Project acceptance summary report
Feasibility Study Report
The purpose of writing the feasibility study report is to explain the feasibility of the software development project in terms of technical, economic and social conditions, comment on the various options that may be selected in order to reasonably achieve the development goals, and explain and demonstrate the selected options . The content of the feasibility study report includes the premise of the feasibility study, the analysis of the existing system, the proposed system, alternative system solutions, investment and benefit analysis, feasibility and conclusion of social factors.
The project proposal
The project proposal formulates a specific plan for the software project implementation plan, including market analysis, a brief introduction to the project, the profit model of the project, the overall framework of the project, the person in charge of each part of the work, the development progress, the development budget of the development funds, the required hardware and software resources, etc. The project proposal is generally written by the project manager according to the client's development plan, as the overall planning of the entire project, and future development work will be executed based on this plan.
Conducting feasibility analysis is a process of self-denial, while writing a project proposal is a process of expressing one's own views to others. Moreover, the project proposal is generally to persuade your boss or investors to do this project, so it must be very complete and analyze all possible pros and cons.
Bidding documents
There is no industry standard for the writing rules of bidding documents for software projects in China. The contents of general bidding documents include brief introduction of project bidding, enterprise informatization project requirements, consulting and implementation requirements, after-sales service requirements and information system requirements, etc. The content of the bidding documents includes the composition of the bidder's business documents, the requirements of the bidding documents and the writing requirements of the project proposal, etc.
needs analysis book
The requirements analysis book is jointly written by the software developer and the customer. The customer describes the expected effect on the function and performance of the system in natural language. The system developed in the future can really meet the needs of customers, and is almost the same as the system expected by customers. The requirements analysis book is a customer-oriented software document, including product overview, main concepts, operation process, function list and explanation, precautions, system environment, etc. Carry out a detailed functional analysis of the system (including customer requirements and suggested functions based on development experience), describe what this product is, what special concepts it has, what function classifications are included, what functions are required, and how the function operates, What details must be paid attention to when implementing, the requirements of the system operating environment, etc.
Building a software system is like building a house. The demand analysis document should describe the intention of the house owner, what kind of house he wants to build, whether to build a small villa with a single family or an apartment with many rooms. How many living rooms, how many bedrooms and how many bathrooms are there in the house, how are these rooms laid out, etc. These questions must be answered in the needs analysis book. On the other hand, since house owners are generally laymen in architecture, it is necessary for house designers to help them discover their own requirements as much as possible from the perspective of architecture.
Outline design book
The outline design book is based on the requirements analysis book, including function realization, module composition, function flow chart, function interface, data dictionary, various issues that need to be considered in software development, etc. These problems have entered the software documentation in the computer field since the writing of the outline design book. Since the requirement analysis document may change at any time, the outline design document is not static after it is formulated. It will change with the change of the requirement analysis document. Starting from the requirement design document, the functional modules of the system, the database Requirements, architecture and other general direction issues.
In the process of building a house, the outline design book is equivalent to the main structural drawing of the house. What needs to be decided at this time is the layout of the house, materials, piping layout and other key issues. Once these issues are decided, the outline of the house has been determined. Out. The same is true for the general design document of the software. After the general design document is completed, the skeleton of the software system can be determined, and future work can be carried out on this basis.
detailed design book
The outline design book describes the system from a high level, but it is impossible to carry out actual coding work with such an outline design book. The detailed design book is based on the outline design book, and designs the separated subsystems and functional modules one by one. The design here should be detailed to the specific steps of each module's realization, what operation is completed by pressing the button, click a certain connection What screen to migrate to, but also to draw the prototype of the page, provide the method of interaction with the database, and the form of data representation, all of which must be described in detail in the detailed design book. Of course, due to the complexity and scale of the project, the complexity of the detailed design document will also be different. If a system with simple functions is accompanied by complex software documentation, it will only make the software development more complicated and violate the purpose of establishing the software documentation. On the contrary, if the software system is complex and there are many participants, detailed software documentation must be provided to provide as detailed and comprehensive information as possible to personnel in different roles.
Going back to the example of building a house, after the skeleton of the house is built, it is time to enrich its body. The decoration design is like the detailed design of software, which determines the overall style of the house, how to arrange the four walls of the house, whether to paste wallpaper or brush The paint, the pattern of glass on the windows and doors, how the lighting is arranged, etc. After the decoration design is completed, the whole picture of the future house will be almost inseparable. Similarly, once a successful detailed design document is completed, the implementation method of the future software system will be determined, and coders can start specific coding work according to the detailed design document. And because many implementation details have been considered and analyzed in the detailed design, some technical problems have also been researched and tested in the early stage and finally concluded. Try to find and solve the problems early, so as not to delay the discovery until the later stage of the project. Through a sufficient detailed design process, the coding process can be made simple and easy to achieve a multiplier effect.
Project acceptance summary report
The content of the project acceptance summary report includes the test, acceptance and summary of the completed system. The purpose of testing is to find as many problems as possible and correct them in time before the software product is delivered to users, so as not to wait for users to discover problems during use. The test plan is to plan the implementation process of the entire test. The plan should include the test content, progress, conditions, personnel, selection principles of test cases, and the allowable deviation range of test results. Since the test will be subdivided into several links such as unit test, integration test and system test, the test plan should also be formulated according to the stage.
other documents
In the actual development process of the software system, there are not only the 7 kinds of software documents mentioned above, but also maintenance manuals, user manuals, etc.
After the software system is developed and delivered to the customer, the software development cycle is over. But from the perspective of the software life cycle, the development cycle is only a part of the life cycle, and more time lies in the service period of the software. Unlike tangible products, software will not experience material loss and depreciation over time. However, during the operation of the software, various problems may be found, which may be slightly different from the functions expected by the customer, or may not be implemented correctly. requirements, this is commonly referred to as a defect. Almost no one dares to assert that there will be no problems at all after the software they develop is put into use. The only difference is the number of defects. Therefore, after the software is put into use, there are maintenance problems like tangible products.
The maintenance work may be implemented by the developer of the software system, or it may be that the client has relevant technical personnel. Whether it is maintained by the developer or the customer's technicians, it needs to be implemented with the help of the maintenance manual, because even for the developer, after they complete the development of a software, they will soon enter the development of the next new system , and with the passage of time, the memory of the original system began to blur, and gradually it was impossible to clearly recall the details of the development at that time. It is even more difficult for the customer's maintenance personnel to know how to maintain the software system. Therefore, the maintenance manual plays the role of technical support. By viewing the maintenance manual, software problems can be diagnosed and corresponding measures can be taken to solve them.
In order to provide technical support, the maintenance manual should include product introduction, system information, initial environment setting, system configuration, data management and backup, technical question answering and contact information, etc. Since the maintenance manual is aimed at people with certain computer-related knowledge, its content should be relatively professional, and strive to describe the solution to the problem in a rigorous manner.
The readers of the user manual are the end users of the software. Users need to obtain various information about the software system from the manual. Therefore, the user manual must describe the functions, performance and user interface of the software in detail, so that users can understand how to use the software. software. The readers of the user manual are usually people without computer-related knowledge, which determines that the language written in the user manual must be non-professional, which is completely different from the detailed design book mentioned above. It does not need to care whether the software system is How to implement, what excellent architecture, advanced development technology, etc., it only needs to care about what functions the software can provide to end users, how to operate the software to obtain this function, and what should be paid attention to in the process of using the software wait.
For the completed house, no one will specially write an instruction manual, because the house is familiar to everyone, and its functions and usage methods are self-evident. Since a house is a tangible entity, the difference between a house and a house can be seen at a glance only by visiting it in person. Software systems are different. With different application fields, the differences between software are also quite large, just as the saying goes, "interlacing is like a mountain". Due to the characteristics of the software, the user manual plays a role that cannot be ignored in the software product, and the user manual becomes a powerful weapon to promote the software.
The format of software documentation is not fixed either. Each company may have its own set of standards, and may discuss with users to form a new software documentation structure. Even so, the basic content of these software documents is consistent.