Internet companies, technical side, is it necessary to write documentation? \

It is necessary. \

What document should I write?

Write at least a master design document, a detailed design document. \

Why not?

Maybe they don’t have time, maybe they don’t know how to write, maybe they don’t want to write.

This article tries to share some experiences and solve the problem of “not writing”. \

** General design document, detailed design document, what should be included? ** General design and detailed design should include: **** (1) Requirements: generally described in the language of the product, this section can copy the story list part of the product requirements document; (2) Noun explanation (optional) : Students in non-related fields need to see some conceptual things that the document needs to understand in advance; (3) Design objectives: they are divided into functional objectives and performance objectives. Functional objectives are generally technical descriptions of product requirements, while performance objectives are performance evaluations based on data provided by products. In general, a new service 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, there will be a simple architecture diagram, accompanied by text to briefly explain the architecture; (2) Module introduction: If there are many modules in the architecture diagram, the functions of each module need to be briefly introduced; (3) Design and compromise: design and compromise is the most important part of the overall design; (4) Potential risks (optional); When exporting the overall design, many schemes are still uncertain, so the overall design focuses on “scheme compromise”, which needs to be confirmed in the design review meeting. After the overall design review is completed, all schemes should be confirmed and detailed design of each module needs to be output. Detailed design focuses on “detail”, which should include: (1) Summary of overall design conclusions (optional) : There is a brief overview of the conclusions agreed on the overall design, indicating that detailed design is the realization of these conclusions; (2) Interaction process: Brief interaction can be explained in text, and complicated interaction suggestions can be explained by flow charts, interaction diagrams or other graphs; (3) Database design: should this be placed in the general setting or detailed setting? (4) Interface details: input parameters, output parameters, according to the interface front end, back end, APP, QA can do parallel coding implementation; (5) Other details: such as formulas; Theoretically, with the detailed design out, whoever gets the detailed design document should be able to complete the project. Other best practices? (1) The architecture diagram or flow chart of a large system or complex process will be very large, often much larger than a page of A4 paper or Word. At this time, it is not appropriate to paste the graph directly in Word, and it will be difficult to see it clearly. It is suggested to put the graph on wiki and paste the link directly in the document. (2) The source files of Viso or other graphics must be saved, otherwise they will have to be redrawn in the future, and the cost can be imagined; \

Design and compromise (1) Design and compromise is the most important content of the general design, the general design review, is mainly to discuss the pros and cons of these compromises; (2) After the review, not only should the conclusion be publicized by email, but also should be updated in the general design to explain the final decision to use which scheme, why this scheme; Based on my own experience, taking over other people’s modules, projects, getting code and documentation, the design scheme is a complete mystery to me!! (3) Sometimes the optimal design scheme may not be adopted due to scheduling or other reasons. In this case, the decision-making process and reasons should be recorded in the general design. (4) Finally, the design compromise is a good opportunity to explain myself: because of the project schedule, or historical problems, I had to adopt such a design, do not scold me. \

Performance objectives performance objectives are an essential part of the new module documentation. If many projects have a significant impact on performance, they must also be written. Performance generally may include the following parts: (1) Average daily requests: generally from the evaluation of product personnel; (2) Average QPS: the average daily request is divided by 4W seconds. Why is it 4W seconds? 24 hours is 86400 seconds. (3) Peak QPS: generally, it can be calculated as 2~4 times of QPS; Voiceover: See “Architecture, How to Design capacity?” .

Internet companies, product iteration fast, may be many companies do not have “document” said. But in fact, well documented, system and project maintenance is very helpful. Voiceover: Clear documentation, small changes in the development stage; Future iterations cost less.

The Architect’s Path – Sharing implementable techniques ****

Related recommendation: \

Does your company write design documents?