The design documents that R&D engineers (RD) need to write are mainly divided into: overall design document + detailed design document , hereinafter referred to as "general design" + "detailed design".
Parts that should be included in both the general design and the detailed design:
(1) Requirements : Generally described in the language of the product, this piece can be copied from the story list part of the product requirements document;
(2) Glossary (optional): Non-related fields
(3) Design goals : It is divided into functional goals and performance goals. Functional goals are generally technical descriptions of product requirements, and performance goals are given according to the product . Data to evaluate performance. Generally speaking, new services must have a performance goal, which may affect the design.
In addition to the parts that should be included, the overall design generally includes:
(1) System architecture : Generally speaking, there will be a simple architecture diagram, and a brief description of the architecture with text;
(2) Module introduction : if the architecture diagram There are many modules, and the functions of each module need to be briefly introduced;
(3) Design and compromise : Design and compromise are the most important parts of the overall design ;
(4) Potential risks (optional);
when outputting the overall design, many The proposal is still uncertain and needs to be confirmed at the design review meeting.
The overall design focuses on "schematic compromise". After the overall design review is completed, all schemes should be confirmed at this time, and the detailed design of each module needs to be output. The detailed design focuses on "detailed":
(1) Summary of overall design conclusions (may be (Optional): There is a brief overview of the conclusions reached on the overall design, explaining that the detailed design is the realization of these conclusions;
(2) Interaction process : Brief interaction can be described in text, complex interaction is suggested to use flow chart, interaction diagram or other Graphics to illustrate;
(3) Database design : should this be placed in the general design or the detailed design?
(4) Interface form : With database + interface + process, other students can basically get the detailed design documents;
(5) Other details : such as formulas, etc.
After the detailed design is theoretically output, no matter who takes it Once this detailed document is reached, the project can be completed.
Personal practice sharing:
1. Big picture
(1) For large systems or complex processes, the structure diagram or flow chart will be very large, often much larger than a page of A4 paper or word. At this time, it is not appropriate to paste graphics directly in word. If you can't see it clearly, it is recommended to put the picture on the wiki, and paste the link directly in the document; (2) Be sure to save the source file
of viso or other graphics , otherwise it will be redrawn if it is changed in the future, and the cost can be imagined;
2. Design and compromise
(1) Design and compromise are the most important content in the general design. During the general design review, the main purpose is to discuss the pros and cons of these compromises ;
(2) After the review, not only should the conclusion be known by email, but also in the generalUpdate it in the design, explain which scheme to use and why it is used in the end; according to my own experience, take over other people's modules, projects, get code and documents, the design scheme is completely a mystery to me! ! !
(3) Sometimes due to scheduling or other reasons, the optimal design plan may not be adopted. In this case, the process and reasons for decision-making should be recorded in the general design;
(4) Finally, design compromise is a good self Opportunity to defend: I had to adopt such a design because of the progress of the project or the problems left over from history. Don't scold me again .
3. Performance goals
Performance goals are an essential part of the new module documentation. If many projects have a great impact on performance, performance goals must also be written. Generally speaking, performance may include the following parts:
(1) Average daily requests: generally from products Evaluation of personnel;
(2) Average QPS: The average daily request is divided by 4w seconds, why is it 4w seconds, 24 hours is converted into 86400 seconds, and the active time of users is calculated as the day, and divided by 2 to obtain 4w seconds;
(3) Peak QPS: Generally, it can be calculated as 2~4 times of QPS;
Internet companies, product iteration blocks, long project cycles, and basically no "documentation", but in fact, writing good documents is very helpful for the future maintenance of the system and the project.