Documents and technologies in software are equally important

Next, let's talk about my understanding of the document.

First, let's take an example: everyone who is engaged in software programming has read the API manual. Think carefully about the manual you have read. You feel that it is easier for you to read it.

My personal experience is Microsoft's document, which presents the customer with a very detailed sense of attention. An API function uses a lot of text to explain this function. This illustrates a problem. It is very important to compile a program for software, but the document is equally important. Microsoft can do so well and become a giant in the software industry. That's our benchmark, that is the flag of our learning.

Software documentation can serve as a bridge for programmers to compile programs, help managers supervise and manage software development, and help users understand the work and operations of software, it is helpful for maintenance personnel to effectively modify and expand documents, and 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. No emphasis on document writing or improper arrangement of 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. It is impossible to obtain high-quality documents. 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; readers should be distinguished before the document compilation, and readers of different types and levels should decide how to adapt to their needs. For example, management documents are mainly for management personnel and user documents are mainly for users. These two types of documents should not be like development documents (for software developers) so much use of software terminology.

② Accuracy: The document text should be very accurate and there should be no ambiguity description. The content of several documents on the same subject should be consistent and there should be no conflict.

③ Clarity: the document should be concise. If possible, appropriate charts should be used to enhance clarity.

④ Integrity: Any document should be complete and independent. It 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, there is no difference in the user manual and operation book of the same project in terms of functions, performance, and implementation environment of the project. In particular, avoid referencing other documents in the document. For example, some paragraphs are not described in detail, but are described in the form of "see ×× document ×× section", which will cause a lot of inconvenience to readers.

⑤ Flexibility: there are many differences in the scale and complexity of different software projects. 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; because the documents prepared in each development stage are closely related to the work completed in each stage, the documents generated in the first and second stages will gradually expand with the development work, has a certain inheritance relationship. Documents provided between various development stages of a project must have traceable relationships. For example, a software requirement must be reflected in the design specification, test plan, and user manual. Tracking should be implemented when necessary.

For programming, programmers can compile good programs. How to present these things to customers (who only know the business and do not know the program) is a kind of flexibility, A learning direction from Microsoft.

I hope that Chinese software will also recognize its own shortcomings, strengthen the maintenance and construction of later programs, enhance the availability of programs, and strengthen the construction of documents, so that China's software industry will fly sooner or later!

We hope that each of us will contribute to the future of our actions.