How to Write detailed design documents

In most software projects, no detailed design is required at the end, or the detailed design documents are supplemented after development. The quality is not optimistic, and documents and systems are often not synchronized, the detailed design documents are completely in the form, which does not provide practical help for the work.

So should we write a detailed design document? How can we make the detailed design document play its due role? Let's take a look at the benefits and problems of detailed design and writing detailed design documents.

·What is a detailed design?

The detailed design is relative to the Outline Design and an important part of the waterfall development process. Based on the high-level design of the outline design, each module is logically implemented, it is the main reference material of the coding stage and the concrete implementation of the idea of gradually refining from the top to the bottom.

Detailed design documents include algorithm design, interface design, data structure design, and interaction design of each module. You must clearly define the modules, interfaces, and public objects, specify the various execution conditions and expected running effects of each module program, and correctly handle various possible exceptions.

·Why design in detail?

During the development process, problems caused by incorrect requirements and design and integrity are a major cause of project delays and failures, an important feature of software systems is the continuous construction and improvement of requirements and design. In the process of writing detailed design documents, The detailed design is actually a logical construction of the system, which can effectively verify the integrity and correctness of the requirements.

If you do not write detailed design documents, you will generally go directly to the coding stage from the overview. The materials that developers can refer to are the requirement specification, page prototype, and database design, and cannot be directly developed, communication of information is required to clearly describe the design that cannot be embodied in the page prototype, which is easy to forget and prone to problems, the detailed design document can be used as a communication tool between the requirement personnel, the overall design personnel and the development personnel. The static page cannot be reflected in the design, including the overall design specifications for the module design, it reflects some design decisions, such as the selected algorithms and design considerations for some key issues, so that developers can quickly enter development, improve communication efficiency, and reduce communication problems.

For system function adjustment and later maintenance, the detailed configuration documents provide the module design considerations and decisions, including the relationship between the module and the overall design, the database design referenced by the module, the processing process of important operations, and the design of important business rules. It provides an overview of the module design, clarified the decision-making on the module design. Combined with code comments, the original design can be easily understood.

·Problems

It is troublesome and time-consuming to be written by special people. It will put pressure on the progress and easily lead to work bottlenecks, which will overload the designers, developers have nothing to do. For a database-centered management system, this work is always required. The difference is that it may take a week or two to form a document, however, it is worthwhile to avoid risks and problems. In addition, due to the popularity of advanced languages, more detailed design should be reflected in the code design, documents only reflect some design decisions, coordinate the relationship between the overall design and the module design, and document the design situations that cannot be reflected by the page prototype, therefore, the time spent is limited.

The design content is easy to elaborate, but the design phase cannot be particularly clear and the time is not allowed.
A countermeasure is mentioned above. The document only reflects the design decisions and the information that the page prototype cannot reflect, the detailed design only reflects some considerations of the overall design for the module design, such as the functional database design. The specific implementation is implemented in the code, the related design is only reflected in the Code.
When requirements and designs need to be constantly updated and constructed, the design documents need to be constantly adjusted and the maintenance of documents needs to be kept up with. Otherwise, the synchronization of documents and systems is hard to be guaranteed, and cause excessive workload. The content of the document is easy to flow to the situation, and the quality is poor. It cannot be a reference manual for developers. First, we need to establish a relevant system. If there is any modification, we should first modify the document for development, ensure the synchronization of documents and systems from the workflow. Second, standardize the quality of documents, what should be written to documents, what should be written, what should be standards, and what is the granularity, the syntax should be organized with clear standards and considerations. At the same time, an audit document review and review system should be established to fully ensure the use of the system.

 

·How should I write detailed design documents?

The following describes how to write a detailed design document that meets the requirements and is practical.

The first is the content of the document. According to different projects and teams, the content of the detailed design document is also different. Generally, the granularity should not be too small, and it cannot replace the design and thinking of developers, however, we need to consider the design decisions, including the relationship with other modules, the overall design, the Operation processing process, and the design of business rules. There is a standard, all design decisions that cannot be reflected by the page prototype and requirement specification, and developers need to understand them, must be written into the document.

Secondly, the document is intended for readers, mainly for module developers and post-maintenance personnel. Module developers learn about the developed functions through detailed design documents and page prototypes, later maintenance personnel learn about a function through the actual system, module code, and detailed design documents.

The other reason is who will write the document. Because the document mainly takes into account design decisions, the person who writes the document should be the responsible Technical Manager and Senior Programmer who participates in the design, it varies depending on the team situation and the project scale and complexity.

It is also necessary to ensure the readability, accuracy, and consistency of documents, establish strict document templates and standards, ensure the readability and accuracy of documents, and establish a review and design review system, to ensure the quality of the design and documentation. In addition, in the workflow process, we must first design, write documents, and then develop them.