Why write a document?

A lot of people talk about RUP or CMMI process improvement The first reaction is that there are many more documents in the process of the project, so many of the documents will not take up a lot of our time. This attitude to look at the document will affect the effectiveness of the process improvement, we are engaged in high-tech creative work, in order to meet the company's provisions and written documents with their own willing to write the content there must be a great difference, to deal with the superficial must not meet the original goal of such standardized documents. I've seen developers coding and then writing design documents, which are basically natural language translations of code, typically reverse engineering.

The key is how to look at the role of the document in the software development process, and if you think of it as an additional burden in the development process, you will write the document for writing the document, and if you think of it as a natural part of the development process, you will be happy to accept it because the document is part of the final delivery of the product. For example, in the following multiplication formula I have made a simple analogy, the original operation requirements are compared to the requirements, the middle of the operation of the step to be compared to the design document, the final result of the operation is the target code we want.

If you can think of a design document as an intermediate step from a requirement to a target code, you will no longer assume that it is a superfluous thing, and that you will be happy to do it. We often do not need to design documents in the daily development, most of the reason is that we have to develop the software is too simple, so simple that we can think clearly in the brain, or more often, we just on the basis of the original code to do some patching work, Without the need to jump directly from demand to the final result on white paper. As the example here shows, it can be done by mental arithmetic, but if I want you to hand-calculate 12345*67890, I'm sure you will use a multiplication formula to get the result. In contrast to the target code, design is a middle product between requirements and code that is closer to the code than the requirements, but it is simpler than the code.

Of course, the document is not only an intermediate process, the main function of the document in the development process is "communication". What is the hardest part of software development? The answer I hear most is "demand", and the confusion of demand is the poor communication and inefficiency between you and the customer and other stakeholders. For a development team, the biggest challenge comes from the communication between team members and stakeholders, and documentation is a basic tool for communication. Small projects involving fewer people, we can choose a lightweight process (with fewer documents to produce); Large projects involve more people, and we can choose a heavyweight process (more documentation is needed to help communicate with team members).

The communication function of the document is mainly in the horizontal and vertical two dimensions, the horizontal aspect document can enable the project member to understand other related personnel's work result, if the designer needs to design the system architecture according to the analyst's requirement document, All project members are required to understand their development tasks according to the project plan developed by the project manager. The longitudinal aspect of the document is also the basis for future maintenance of the system, developers need to read the project's previous design documents to understand the system structure, and then the system can be modified on this basis.

A few people's projects, every day to talk about, you can complete the purpose of communication, a meeting minutes can record all the problems and action plans, the agile process on behalf of XP (EXtreme programming) is more suitable for this small project. For a dozens of-person project, such communication is not appropriate, we need some formal documentation to help team communication, such as: project development plans, software requirements, design documents, test plans and so on, these are to help horizontal communication. In vertical communication, we need some necessary documentation to help deliver key information about the project to future versions of the developer.

Since the main function of the document is to facilitate team communication, it is necessary to develop standards to ensure the effectiveness of communication. For different projects within the same enterprise, we certainly want each project to adopt the same document system, even the document format, so that when we switch from one project to another, we are able to read and understand each document smoothly. A complete set of software project process documentation templates is provided in RUP.

In addition to communication, documentation is also a tool to help us organize our ideas. When many ideas are written down, we will consider their integrity more carefully (for example, the role of the document itself is remembered and added in the process of writing this article); Many of the specious content in the mind will be refined and normalized in a documented process. Think back to the process of collecting requirements from your customers, and each business person will only describe the part of the business process and requirements that he knows, and you need to document everyone's descriptions and then synthesize them into a complete business process and requirements description. Some business processing rules are not standardized in their daily work, may differ slightly from the understanding of different business people, in the process of writing these requirements, we will standardize these business rules, in order to ensure that all business personnel identification.

The document should not be misunderstood as an additional burden, if there is a feeling that there are only two possibilities: either you do not understand the role of the document in the entire project, or the document that the company prescribes is fundamentally unnecessary in this project.