Quality requirements for software development documentation Compilation

To enable software documentation to serve as a bridge between the various types mentioned in the previous section, it helps programmers compile programs and help managers supervise and manage software development, it helps users understand the work of software and the operations they should perform, and helps maintenance personnel to effectively modify and expand the software. The preparation of documents must ensure a certain quality. Poor quality software documentation not only makes it difficult for readers to understand, but also causes a lot of inconvenience to users. It also weakens the management of software (it is difficult for managers to confirm and evaluate the development progress ), increase the cost of software (some work may be forced to rework), and even cause more harmful consequences (such as misoperations ).

The reason for the low quality of software documents may be:

· Lack of practical experience and standards for evaluating document quality.

· Do not pay attention to document writing or make improper arrangements for document writing.

The most common situation is that documents cannot be prepared in a timely manner based on the given progress in the software development process. Instead, documents can be compiled in a way that sets the human force and time when the development work is close to completion. On the other hand, many people are not interested in document preparation compared to program work. So after the program is completed, I have to deal with it and write out the required documents. In this way, high-quality documents cannot be obtained. In fact, it is not easy to get really high-quality documents. Aside from paying enough attention to the document work in terms of understanding, it is often necessary to write the first draft and listen to opinions for revision, it even needs to be rewritten.

High-quality documents should be reflected in the following aspects:

① Targeted

In the past, readers should be distinguished, and readers of different types and levels should decide how to adapt to their needs. For example, management documents are mainly oriented to management personnel, and user documents are mainly oriented to users. These two types of documents should not be like development documents (for software developers) so much use of software terminology.

② Accuracy

The document should be very accurate, and there should be no multi-dimensional descriptions. The content of several documents on the same subject should be consistent and there should be no conflict.

③ Clarity

The document should be concise and, if possible, should be prepared with an appropriate graph table to enhance its clarity.

④ Integrity

Any document should be complete and independent, and should be self-contained. For example, a general introduction should be made to the preface, the content of the center should be provided in the body, and an appendix should be provided to list references if necessary. Several documents of the same subject may be partially the same, and these duplicates are necessary. For example, user manuals and operations for the same project

There is no difference in the description of the project's functions, performance, and implementation environment. In particular, avoid referencing other documents in the document. For example

Some paragraphs are not described in detail, but the method of "See section XXX" will cause a lot of inconvenience to readers.

⑤ Flexibility

The scale and complexity of different software projects vary a lot from each other. The documents listed in figure 6 are for medium-sized software. For small or relatively simple projects, you can make appropriate adjustments or mergers. For example, the user manual and the operation manual can be combined into the user operation manual; the software requirement manual can include the data requirements, so as to remove the data requirement manual; the summary design specification and detailed design specification are combined into the software design specification.

⑥ Traceability

Since the documents prepared in each development stage are closely related to the work completed in each stage, the documents generated in the two stages have a certain inheritance relationship with the gradual expansion of the development work. There must be a traceable relationship between documents provided during each development phase of a project. For example, a software requirement must be reflected in the design instruction, test plan, and user manual. Tracking should be implemented when necessary.