GB/T 8567-1988 Guidelines for the preparation of computer software product development documentation
Some standard content:
National Standard of the People's Republic of China
Guidelines for Computer Software Product Development DocumentationIntroduction
1 Purpose
UDC 681. 3
GB 8567-88
The planning, development and implementation of a computer software constitute a software development project. The implementation of a software development project generally requires a significant investment in human and automation resources. In order to ensure the success of project development, spend these investments in the most economical way, and facilitate operation and maintenance, certain documents need to be compiled at each stage of the development work. These documents, together with computer programs and data, constitute computer software. Documents are an indispensable component of computer software, and their functions are: a. To serve as the work results and end mark of developers in a certain stage; b. To provide managers with the progress and status of the software development process, and convert some "invisible" things in the software development process into "visible" text materials. So that managers can check the progress of the development plan at each stage, so that they can judge whether the original goal has been achieved, and the types and quantities of resources that will continue to be consumed: c. Record technical information during the development process to facilitate the coordination of future software development, use and modification, d. Provide information on the operation, maintenance and training of the software to facilitate mutual understanding of each other's work between managers, developers, operators and users,
e. Report the functions and performance of the software to potential users so that they can determine whether the software can serve their needs. In other words, this guide believes that the preparation of documents must meet the needs of the entire life cycle of computer software. There are two types of documents included in computer software: one is the various charts filled in during the development process, which can be called work forms, and the other is the technical information or technical management information that should be prepared, which can be called documents. This guide stipulates the form of preparation of software documents and provides explanations for these regulations. The purpose of this guide is to ensure that the compiled software documents can indeed play the role that software documents should play. 2 Scope
This guide is a guiding document. This guide recommends that in the development process of a computer software, generally speaking, fourteen types of documents should be generated. These fourteen documents are:
Feasibility study report!
Project development plan:
Software requirements specification,
Data requirements specification:
General design specification:
Detailed design specification,
Database design specification,
User manual:
Approved by the National Bureau of Standards on 1988-01-07
Implemented on 1988-07-01
Operation manual;
Module development dossier:
Test plan:
Test analysis report:
Monthly development progress report;
Project development summary report.
GB 8567--88
This guide will provide guidance on the preparation of these fourteen documents recommended in the development process. At the same time, this guide is also the inspection criterion for the writing quality of these fourteen documents. However, this guide does not involve the question of how to fill in the work form during the software development process. Generally speaking, a software is always a component of a computer system (including hardware, firmware and software). In view of the diversity of computer systems, this guide generally does not involve the document compilation issues in the entire system development. This guide is only a document compilation guide during the software development process.
3 Document usersbzxz.net
For people who use documents, the types of documents they are concerned about vary depending on the work they undertake. Managers: feasibility study report, project development plan, module development dossier, monthly development progress report, project development summary report; Developers: feasibility study report, project development plan, software requirements specification, data requirements specification, outline design specification, detailed design specification, database design specification, test plan, test analysis report; Maintenance personnel: design specification, test analysis report, module development dossier: User: user manual, operation manual. Although this guideline proposes requirements for document preparation in software development, it does not mean that all these documents must be handed over to users. The types of documents that users of a software should receive are stipulated in the contract signed between the supplier and the user. The first part of the document preparation guide
4Software life cycle and the preparation of various documentsA computer software, from the date of the emergence of an idea, through the successful development of the software and its use, until the final decision to stop using it and replace it with another software, is considered to be a life cycle of the software. Generally speaking, the software life cycle can be divided into the following six stages:
Feasibility and planning research stage
Requirement analysis stage
Design stage
Implementation stage
Testing stage
Operation and maintenance stage
GB 8567-88
In the feasibility study and planning stage, the development goals and general requirements of the software should be determined, feasibility analysis, investment-return analysis, development plan should be formulated, and the documents to be prepared should be completed. In the requirement analysis stage, the system analyst conducts a system analysis of the designed system.Determine the various functions, performance requirements and design constraints of the software, and determine the requirements for document preparation. As the result of this phase of work, generally speaking, the software requirements specification, data requirements specification and preliminary user manual should be written. In the design phase, system designers and programmers should propose multiple designs based on repeated understanding of software requirements, analyze the functions that each design can perform and compare them with each other, and finally determine a design, including the structure of the software, the division of modules, the allocation of functions and the processing flow. In the case of a complex system to be designed, the design phase should be decomposed into two steps: the outline design phase and the detailed design phase. In general, the documents to be completed include: outline design specification, detailed design specification and the first draft of the test plan. In the implementation phase, the source program coding, compilation (or assembly) and error debugging should be completed to obtain a program list without syntax errors, the module development file should be started, and the user manual, operation manual and other user-oriented documents should be completed. The preparation of the test plan should also be completed.
In the testing phase, the program will be fully tested and the compiled documents will be checked and reviewed. Generally, the module development dossier and test analysis report are completed. As the end of the development work, the produced programs, documents and development work itself will be evaluated item by item, and finally the project development summary report will be written.
During the entire development process (i.e., the first five stages), the development team must compile a monthly development progress report on a monthly basis. During the operation and maintenance stage, the software will be continuously maintained during operation and use, and necessary and possible expansions and deletions will be made according to new requirements.
For a software, the relationship between each stage of its life cycle and various file writing work can be seen in Table 1, and the writing of some files may be continued in several stages. Table 1 Document preparation in each stage of the software life cycle Document
Feasibility study report
Project development plan
Software requirements specification
Data requirements specification
Test plan
Outline design specification
Detailed design specification
Feasibility study
and planning stage
Requirements analysis stage
Operation and maintenance stage
Database design specification
Module development file
User manual
Operation manual
Test analysis report
Monthly development progress report
Project development summary
5 Factors to consider in document preparation
GB 8567--88
Continued Table 1
Feasibility Study
and Planning Phase
Requirement Analysis Phase
Operation and Maintenance Phase
Document preparation is a continuous and hard work process. It is a complete process from the initial formation, repeated inspection and modification, to the formal delivery of programs and documents. Each step requires great efforts from the staff. To ensure the quality of document preparation, it is necessary to reflect the characteristics of each development project and also pay attention to not spending too much manpower. To this end, the following factors should be considered in preparation. 5.1 Readers of Documents
Each document has a specific reader. These readers include individuals or groups, members of the software development unit or the public in society, technicians engaged in software work, managers or leading cadres. They look forward to using the contents of these documents to carry out work, such as designing, writing programs, testing, using, maintaining or conducting plan management. Therefore, the authors of these documents must understand their own readers, and the preparation of these documents must pay attention to adapting to the level, characteristics and requirements of their specific readers. 5.2 Duplication
There are obviously some duplications in the content requirements of the fourteen documents listed in the second part of this guide. There are two kinds of obvious duplications. The introduction is the content that each document must include to provide readers with a general outline. The second kind of obvious duplication is the description part in various documents, such as the description of functional performance, the description of input and output, the equipment included in the system, etc. This is for the convenience of each document's respective readers. Each product document should be self-contained, and try to avoid having to refer to another document when reading one document. Of course, in each document, the introduction, description and other parts that are repeated in other documents should still have some differences in wording, terminology used, and level of detail to meet the needs of different readers of various documents. 5.3 Flexibility
In view of the fact that software development is a creative and mental work, and in view of the fact that different software vary greatly in scale and complexity, this guide believes that a certain degree of flexibility should be allowed in the preparation of documents. This flexibility is reflected in the following clauses. 5.3.1 Types of Documents to be Prepared
Although this guideline considers that in general, there are fourteen types of documents that should be generated during the development of a software, for a specific software development project, sometimes it is not necessary to prepare so many documents, and several documents can be combined into one. Generally speaking, when the scale, complexity and success or failure risk of the project increase, the scope, management procedures and level of detail of document preparation will increase accordingly. On the contrary, it can be appropriately reduced. In order to properly grasp this flexibility, this guideline requires the implementation of the principle of division of labor and responsibility, which means: the leadership of a software development unit should formulate an implementation regulation for document preparation requirements based on the professional field of the application software contracted by the unit and the management capacity of the unit, mainly: what documents should be formed under different conditions? What is the level of detail of these documents? Each project leader of the development unit must conscientiously implement this implementation regulation. Two examples of such regulations can be found in Appendix 0 (reference) of this guideline;
b. For a specific application software project, the project leader should determine a document preparation plan based on the above implementation regulations, which includes:
(1) What kind of documents should be prepared and how detailed? (2) The person in charge of preparing each document and the progress requirements; (3) The person in charge of review and approval and the time schedule; (4) The person in charge of maintaining, modifying and managing each document during the development period, as well as the approval procedures. Each task must be assigned to a person:
This document preparation plan is an important part of the entire development plan; c. The relevant designers must strictly implement this document preparation plan. 5.3.2 Degree of detail of the document
The length of the document drafted from the same outline often varies, ranging from a few pages to hundreds of pages. This guideline allows for such differences. The degree of detail depends on the scale and complexity of the task and the project leader's judgment on the degree of detail required for the software development process and operating environment.
5.3.3 File Expansion
When the system being developed is very large (for example, the source code exceeds one million lines), a file can be divided into several volumes. It can be compiled separately for each system, or divided into multiple volumes according to content. For example: the project development plan may include: quality assurance plan, configuration management plan,
user training plan,
installation implementation plan;
the system design specification can be divided into: system design specification, subsystem design specification:
|The program design specification can be divided into: program design specification, interface design specification,
version description;
operation manual can be divided into: operation manual, installation implementation process;
test plan can be divided into: test plan, test design description,
test procedure,
test case:
test analysis report can be divided into: comprehensive test report, acceptance test report;
project development summary report can also be divided into project development summary report and resource and environmental statistics. 5.3.4 Expansion and contraction
In some documents, the chapter and article titles provided in this guide can be used, but there are a series of factors that need to be discussed separately in the articles. This guide believes that all articles can be expanded and further subdivided to meet actual needs. Conversely, if some details in the chapters and articles are not necessary, they can also be contracted according to actual conditions. At this time, the numbering of the chapters and articles should be changed accordingly. 5.3.5 The form of program design
This guide does not specify or restrict the form of program design. It can be expressed in the form of a flowchart, a decision table, or other forms, such as a program design language (PDL), a problem analysis diagram (PAD), etc. 128
5.3.6 The form of file expression
GB8567-88
This guide does not specify or restrict the form of file expression. It can be expressed in natural language or formal language. 5.3.7 Other types of documents
When the types of documents specified in this guideline cannot meet the special needs of some application departments, they can establish some special document type requirements, such as software quality assurance plan, software distribution and management plan, etc. These requirements can be included in the implementation regulations of document preparation of the unit.
6 Management of document preparation
Document preparation must be coordinated with management work to make the compiled documents truly play their role. Document preparation actually runs through the entire development process of a software. Therefore, the management of documents must run through the entire development process. The following four management tasks must be carried out during the development process. 6.1 Document formation
Every member of the development team, especially the project leader, should realize that documents are an indispensable part of the software product. In each stage of the software development process, the compilation of various product documents must be completed in a timely manner in accordance with regulations. The decisions made and the results obtained in a development step must be written into the documents in a timely manner; the development team must conduct a timely and strict review of these documents. The formation of these documents is a sign that the development work at each stage is formally completed. These documents must be signed by the author, reviewer and approver, and must have the date of completion of the writing and review and the date of approval. 6.2 Classification and identification of documents
In the process of software development, many documents are generated. In order to facilitate storage, search, use and modification, the documents should be classified and organized hierarchically. A software development unit should establish a method for identifying the documents of the unit so that each page of the document has a clear identification. For example, the documents can be classified and identified according to the following four levels. a. Identification of the project to which the document belongs; b. Identification of the type of document; c. Different version numbers of the same document; d. Page number. In addition, each document should be assigned its own confidentiality level and distribution scope according to the nature of the project. 6.3 Control of documents
In the process of software development, as the program is gradually formed and modified, various documents are constantly generated, modified or supplemented. Therefore, careful control must be exercised to maintain the consistency of files and program products, the consistency between various files, and the security of files. This control is manifested in the following ways:. For a development team engaged in a software development project, a full-time file manager (interface management engineer or file manager) should be set up; in the development team, two sets of master texts of all existing files of the project should be kept centrally, and the file manager is responsible for keeping them:
b. Each document submitted to the file manager must be signed by the author, reviewer, and approver; ℃. The contents of the two sets of master texts must be completely consistent; one set can be lent, and the other set must not be lent, in case of any accident, the lent master text must go through the lending procedures when it is lent, and the cancellation of the lending procedures must be done when it is returned; d. Staff members of the development team may, according to work needs, hold some files during the development of this project, namely the so-called personal files, including files required for them to complete their tasks and files compiled by them in the process of completing their tasks: but such personal files must be copies of the main text and must be completely consistent with the main text. If they need to be modified, the main text must be modified first; e. The personal files owned by different developers are usually various subsets of the main text: a subset refers to a collection of several files that are copied and assembled from various parts of the main text according to the work needs of personnel or departments with different tasks; the file manager should make a list of distribution objects for different subsets, and distribute the files to the relevant personnel or departments in a timely manner according to the list; f. If a document has been replaced by another new document, the original document should be cancelled. The document manager should organize the main text at any time, reflect the changes and additions of the document in time, distribute the document in time, and share. When the development work of a project is about to end, the document manager should collect the personal documents of each member of the development team one by one and check the content of these personal documents. Experience shows that these personal documents may be more detailed than the main text, or different from the content of the main text. The relevant personnel must be carefully supervised to make modifications so that the main text can truly reflect the actual development results. 6.4 Document modification management
At any time during the development of a project, all members of the development team may request to modify the existing results of the development work - the document. The reasons for making a modification request may be various, and the impact caused by the modification may be small, or it may involve many aspects of the project. Therefore, the modification activities must be carried out with caution, the modification activities must be managed, and the procedures for the modification activities must be implemented so that the entire modification activities are carried out in a controlled manner. The modification activities can be divided into the following five steps:. Any member of the proposed development team can propose a modification suggestion to the project leader. For this purpose, a modification suggestion form should be filled out, indicating the content of the modification, the modified files and parts, and the reasons for the modification; b. Review The project leader or the person designated by the project leader will review the modification suggestion, including reviewing the necessity of the modification, determining the scope of the modification, and studying the methods, steps and implementation plan for the modification; c. Review is generally conducted by the project leader, including verifying the purpose and requirements of the modification, verifying the impact of the modification activities, and reviewing whether the modification activity plan is feasible: d. Approval In general, the approval authority belongs to the department head of the development unit. When approving, it is mainly to determine the sequence of various activities in the modification work and their respective completion dates to ensure that the entire development work is completed according to the original planned date; e. Implementation The project leader arranges the responsible personnel of each modification activity to make modifications according to the approved modification activity plan, establishes modification records, generates new documents to replace the original documents, and finally submits the documents to the file management personnel for archiving and distributes them to the relevant holders. Part 2 Content requirements for various documents
This part will provide content requirements for the fourteen documents mentioned in the introduction as technical standards for document preparation. 7 Feasibility Study Report
The purpose of writing a feasibility study report is to: explain the feasibility of the implementation of the software development project in terms of technical, economic and social conditions: review the various options that may be selected in order to reasonably achieve the development goals, and explain and demonstrate the selected option. The content requirements for the feasibility study report are as follows: 7.1 Introduction
7.1.1 Purpose of writing
7.7.2 Background
7.1.3 Definition
7.1.4 References
7.2 Prerequisites for feasibility study
7.2.1 Requirements
7.2.2 Objectives
7.2.3 Conditions, assumptions and limitations
7.2.4 Methods for conducting a feasibility study
7.2.5 Evaluation criteria||t t||7.3 Analysis of existing system
7.3.1 Data flow and process flow
7.3.2 Workload
7.3.3 Costs
7.3.4 Personnel
7.3.5 Equipment
7.3.6 Limitations
7.4 Proposed system
7.4.1 Description of the proposed system
7.4.2 Data flow and process flow Program
7.4.3 Improvements
7.4.4 Impact
7.4.4.1 Impact on equipment
7.4.4.2 Impact on software
7.4.4.3 Impact on user organizations
7.4.4.4 Impact on system operation
7.4.4.5 Impact on development
7.4.4.6 Impact on location and facilities
7.4.4.7 Impact on expenditure
7.4.5 Limitations
7.4.6 Feasibility in terms of technical conditions
7.5 Alternative system solutions
7.5.1 Alternative system solution 1
7.5.2 Alternative system solution 2
7.6 Investment and benefit analysis
7.6.1 Expenditure
Capital construction investment
7. 6.1.1
7.6.1.2 Other one-time expenses
7.6.1.3 Non-one-time expenses
7.6.2 Income
7.6.2.1 One-time income
7.6.2.2 Non-one-time income
7.6.2.3 Unquantifiable income
7.6.3 Income/investment ratio
7.6.4 Investment recovery period
7.6.5 Sensitivity analysis
7.7 Feasibility in social conditions
7.7.1 Legal feasibility
7.7.2 Feasibility in use
7.8 Conclusion
8 Project development plan
GB8567--88
The purpose of preparing a project development plan is to record in the form of a document the arrangements made for the responsible personnel for each task in the development process, the development progress, the required budget, the required software and hardware conditions, etc., so as to carry out and check the development work of this project according to this plan. The requirements for the preparation content are as follows:
8.1 Introduction
8.1.1 Purpose of preparation
8.1.2 Background
8.1.3 Definition
8.1.4 References
8.2 Project Overview
8.2.1 Work Content
8.2.2 Main Participants
8.2.3 Products and Results
8.2.3.1 Procedures
8.2.3.2 Documents
8.2.3.3 Services
8.2.3.4 Non-transferable products
8.2.4 Acceptance Criteria
Completed Items PurposeLatest deadline
8.2.6 Reviewers and approvers of this plan
8.3 Overall implementation plan
8.3.1 Decomposition of work tasks
8.3.2 Interface personnel
8.3.3 Schedule
8.3.4 Budget
8.3.5 Key issues
8.4 Support conditions
8.4.1 Computer system support
8.4.2 Work to be undertaken by the user
8.4.3 Conditions to be provided by external units
8.5 Key points of the special plan
9 Software Requirements Specification
GB 8567-88
The purpose of preparing the software requirements specification is to enable both users and software developers to have a common understanding of the initial requirements of the software, so that it can serve as the basis for the entire development work. The requirements for the preparation of software requirements specifications are as follows: 9.1 Introduction
9.1.1 Purpose of preparation
9.1.2 Background
9.1.3 Definition
9.1.4 References
9.2 Task Overview
9.2.1 Objectives
9.2.2 User characteristics
9.2.3 Assumptions and constraints
9.3 Requirements Specification
9.3.1 Functional Specification
9.3.2 Performance Specification
9.3.2.1 Accuracy
9.3.2.2 Time Characteristics Requirements
9.3. 2.3 Flexibility
9.3.3 Input and output requirements
9.3.4 Data management capability requirements
9.3.5 Fault handling requirements
9.3.6 Other special requirements
9.4 Operating environment requirements
9.4.1 Equipment
9.4.2 Support software
9.4.3 Interface
9.4.4 Control
10 Data requirements specification
GB856788
The purpose of preparing the data requirements specification is to provide technical information on the description of the processed data and the data collection requirements throughout the development period. The content requirements for the preparation of data requirements instructions are as follows: 10.1 Introduction
10.1.1 Purpose
10.1.2 Background
10.1.3 Definition
10.1.4 References
10. 2 Data Decompilation Description
10.2.1 Static Data
10.2.2 Dynamic Input Data
10.2.3 Dynamic Output Data
10.2.4 Internally Generated Data
10.2.5 Data Agreement
10.3 Data Collection
10.3.1 Requirements and Scope
10.3.2 Input Undertaker
10.3.3 Processing
10.3.4 Impact
11 Summary Design Specification
The summary design specification can also be called the system design specification. The system here refers to the program system. The purpose of compilation is to explain the design considerations for the program system, including the basic processing flow of the program system, the organizational structure of the program system, module division, function allocation, interface design, operation design, data structure design and error handling design, etc., to provide a basis for the detailed design of the program. The requirements for the content of the summary design specification are as follows:
11.1 Introduction
11.1.1 Purpose
11.1.2 Background
11.1.3 Definition
11.1.4 References
11.2 Overall design
11.2.1 Requirements
11.2.2 Operating environment
11.2.3 Basic design concepts and processing flow11.2.4 Structure
11.2.5 Relationship between functional requirements and programs
11.2.6 Manual processing
11.2.7 Unresolved issues
11.3 Interface design
11.3.1 User interface
11.3.2 External interface
11.3.3 Internal interface
11.4 Operation design
11.4.1 Operation module combination
11.4.2 Operation control
11.4.3 Operation time
11. 5 System data structure design
11.5.1 Key points of logical structure design
11.5.2 Key points of physical structure design
11.5.3 Relationship between data structure and program
11.6 System error handling design
11.6.1 Error message
11.6.2 Remedial measures
System maintenance design
12 Detailed design specification
GB 8567 -~ 88
Detailed design specification can also be called program design specification. The purpose of preparation is to explain the design considerations of each program (each module or subroutine) in each level of a software system. If a software system is relatively simple and has few levels, this document may not be written separately, and the relevant content can be merged into the outline design specification. The requirements for the content of the detailed design specification are as follows: 12.1 Introduction
12.1.1 Purpose of writing
12.1.2 Background
12.1.3 Definition
12.1.4 References
12. 2 Organization structure of the program system
12.3 Program 1 (identifier) design description
12.3.1 Program description
12.3.2 Function
12.3.3 Performance
12.3.4 Input items
12.3.5 Output items
12.3.6 Algorithms
12.3.7 Process logic
12.3.8 Interface
12.3.9 Storage allocation|| tt||12.3.10 Note design
12.3.11 Constraints
12.3.12 Test plan
Unresolved issues
12.4 Program 2 (Identifier) design description
13 Database design specification
GB8567--88
The purpose of compiling the database design specification is to make specific design provisions for all identifiers, logical structures and physical structures of the database under design. The content requirements are as follows: 13.1 Introduction
13.7.1 Purpose
13.7.2 Background
13.1.3 Definitions
13.1.4 References
13.2 External design
13.2.1 Identifiers and status
13.2.2 Procedures for using it
13.2.3 Conventions
13.2.4 Special instructions
13.2.5 Support software
13.3 Structural design
13.3.1 Conceptual structural design
Logical structural design
13.3.3 Physical structural design
13.4 Application design
13.4.1 Data dictionary design
Security and confidentiality design
14 User manual
The preparation of the user manual is to use non-specialized language to fully describe the functions and basic usage methods of the software system. Through this manual, users (or potential users) can understand the purpose of the software and determine how to use it under what circumstances. The specific content requirements are as follows:
14.1 Introduction
14.1.1 Purpose of writing
14.1.2 Background
14.1.3 Definition
14.1.4 References
14.2 Purpose
14.2.1 Function
14.2.2 Performance
Tip: This standard content only shows part of the intercepted content of the complete standard. If you need the complete standard, please go to the top to download the complete standard document for free.