1. Overview
Most engineers don't pay attention to the writing of design documents. For a requirement, after some simple discussions, they write a simple solution or even just think about it and start coding.
Often this development method will cause developers to not consider the details carefully, and there will be many pits in the development process. In the future, a lot of manpower will be expended on the way to mine pits or make up pits, which will affect the launch time at light, or appear online at worst. case, affecting the business.
Writing design documents and is able to help developers complete the process of what -> what -> how to do it. For example, you may be very familiar with a technology or concept, but when you want to say it or write it out for others to see, you may find that you have not considered some technical details clearly.
When you're writing a design document, you're forcing yourself to figure out every detail and figure it out. In this way, in the actual development process, you will step on the pit less and not step on the pit.
2. What does a good design document need?
For the writing of a design document, it should meet the STAR principle. At the same time, a good design document needs to consider various implementation schemes in the industry, and cannot work behind closed doors.
Based on this, I think it will be mainly divided into 8 parts. They are project background, project goal, demand analysis, scheme comparison, outline design, detailed design (storage model design, interface design), development and launch plan, and plan schedule.
For the detailed design, it is necessary to store the design that should have the storage model, and the need to interact with the design that should have the corresponding interface. The main points of writing each section are described in detail below.
2.1 Project Background
Mainly to sort out the main problems and pain points in the current system. The main problems and pain points cover a wide range and can be mainly analyzed from the perspectives of stability, business and operation.
- For stability, the corresponding data indicators can be given for specific problems, such as the relevant call time, TP90 time, customer complaint rate, order success rate, etc.
- For business, it can be analyzed from the perspective of business development and pain points in the industry
- Operation, specific problems can also be given corresponding data indicators, such as the operation and maintenance cost is higher than XXpd and so on.
2.2 Goals
That is, what results need to be achieved after the program is launched, and the specific goals need to be determined in combination with the project background.
- For example, for stability, it is necessary to reduce the customer complaint rate by half, increase the order success rate to 4 9s, and so on.
- From the perspective of operation and maintenance, it is necessary to reduce the operation and maintenance cost to 0 and so on.
Similarly, specific problems need to be analyzed in detail. When setting goals, you can refer to the indicators of the current industry or related systems within the company.
2.3 Demand Analysis
In theory, demand analysis is done by PM, but through demand analysis, developers can more clearly understand and clarify the needs of corresponding users, and through demand analysis, they can also understand whether PM's sometimes demand is "pseudo demand".
The purpose of optimization of related functions and evolution of the system is to provide users with better services. When conducting demand analysis, developers should try their best to use their own systems so that they can truly understand their own systems. The requirement of requirement analysis is to draw a use case diagram to describe all the use cases of the user.
2.4 Scheme comparison
When designing a scheme, it is actually a stage of scheme research, and it is necessary to investigate the implementation of related functions in the industry or some open source systems. And combine it with your own business to evaluate a set of business that is most suitable for you.
The main purpose of the program comparison is to choose one that is suitable for your business. Sometimes you should not use technology for the sake of technology. Simple and appropriate is the best choice.
In the scheme comparison, the development process of each scheme and the matters needing attention can be listed, and finally the scheme comparison table and conclusion can be given.
2.5 Outline Design
After the scheme is selected, the outline design of the scheme needs to be given. In the summary design, the panoramic design used to describe the entire scheme generally needs to include the scheme panoramic design diagram, flow chart and sequence diagram .
- Panoramic design diagram: If the design scheme is for the system dimension, the design diagram needs to reflect the calling relationship of the current system in the entire link, as well as the related field design in the current service, and specific related functions should be listed in the corresponding field; If the design scheme is an internal optimization or transformation scheme of the system, it is necessary to draw a diagram of the internal call hierarchy, in which the module relationship between the systems and the call relationship after the current scheme is launched should be identified.
- Flowchart: Flowchart is used to describe the detailed execution process of the scheme. If the scheme is of system dimension, it is not necessary to draw it.
- Sequence diagram: The dimension of the sequence diagram can be between services and services, showing the calls between services, and the specific interface can list the internal functions of related services.
2.6 Detailed Design
The detailed design includes scheme comparison, storage, interface and other detailed designs.
storage model design
In the storage model design, the DDL design of the related storage model diagram and related tables needs to be given:
The related storage model diagram is the one-to-one, one-to-many mapping relationship of related tables, and the relevant important fields of the current design table. The relevant table creation
SQL needs to be given in the DDL, and each field in the table creation SQL needs to be forced to give a default value. The value and the detailed meaning of the field, and finally the corresponding table index needs to be given
interface design
In the interface design, the definition of the corresponding interface, the definition of the request and response objects, and if it is an rpc interface, such as thrift, also need to define the relevant idl. In addition, you need to define the timeout period of the interface, etc.
- When the interface is defined, swagger can be used to automatically generate documentation
- Interfaces can only be added and adapted. There is no 100% certainty, and interfaces cannot be easily deleted.
2.7 Development and launch plan
Divided into development plan and go-live process
- Development plan: mainly the development process of the following subjects, and the completion time of some project milestones can be listed in detail
- The launch plan mainly includes:
- How to do grayscale
- How to publish, check people after publishing
- How to verify
- rollback strategy
2.8 Project Schedule
Give the schedule table of the project. In addition to the relevant content of each plan, the table should also include the estimated time, the current progress, whether it is delayed, the reason for the delay, and so on.
3. Summary
Design documents are not only written for others to see, but also a process of in-depth thinking. The process of writing is a process of forcing oneself to think. A good design document can not only make readers understand the functions to be developed at a glance, but also avoid the future mining process.
Of course, this article does not cover the writing of all design documents. For example, you can also draw mind maps through MindManager, or use other tasks, as long as the performance is clear.
Friends who have design document writing suggestions or tool recommendations are welcome to leave a message for discussion~