"How to write technical documents? "The comment is surprising. An article on "How to write a good design document" is full of hostility.
I'm not sure whether my ideas are outdated in the new era of the Internet. It seems that writing documents has become a minority. In any case, express your views in a clear-cut manner.
All opinions in this article are personal opinions, and there is no "judgment" to share what you think is correct.
Voiceover: The material in the following text, screenshots from "How to write technical documents? "In the comment, the avatar and name are hidden.
1. 
How to write technical documents? 》In the comments, the most like point is: do not write technical documents, because only in this way, the boss dare not replace ta casually, so that ta is "irreplaceable".
However, "the irreplaceability of the workplace"
does not mean:
"I have buried a lot of hidden pits. Only I know where the hidden pits are, so I am irreplaceable."
Rather, it means:
"I have core competence that other people don't have. It may be attitude, professional ability, or good-looking."
Sunshine positive energy:
Thinking hard in the workplace and keeping your "iron rice bowl" by "digging holes", it is better to work hard to improve your core competitiveness, so that you have the ability to eat wherever you are.
2. The 
second point of view is that the document is written for others to see, for the boss, for the customer, for the person who wants to communicate, and the person who wants to take over the project. Project participants do not need to write documentation.
Why write design documents?
For yourself, let yourself help yourself to think more clearly before writing the code;
for projects, ensure the consistency of information, ensure the controllability of the project, and reduce project risks;
for the team, ensure the precipitation and inheritance of knowledge;
How many subsystems are involved in the project, how many modules are involved in each subsystem, what are the dependencies between modules, how many interfaces need to be provided to each other, what are the parameters of each interface, how upstream and downstream interactions are in the interface implementation process, and what technical solutions are used for core logic Realize... Does the relevant technical people know everything?
Many confident technology gods "think" they understand, but they don't understand. In fact, they just don't understand.
Many "speak clearly" but "unclearly written" are actually not understood.
Only when a project and a technical problem are described in words and logically, it means that the real thinking is clear.
Voiceover: If you land on the paper, you can find many problems in the design.
How does the document ensure the consistency of information and reduce project risks?
To give a simple example, PHP engineers need to provide an HTTP interface to obtain order information, and later need to coordinate with IOS/Android/FE engineers, and QA engineers also need to test.
Isn’t it necessary to put the HTTP interface on paper?
http://daojia.com/order/getinfo?oid=${oid }
cookie: uid=${uid}
cookie: token=${token}
…
RESTFUL interface format, input and output format, the information is PHP/IOS/ Android/FE/QA engineers need clear information, otherwise the related R&D joint debugging and testing work will not be carried out. Does this information need to be communicated verbally every time?
One year after the project went live, the interface needs to be upgraded iteratively. Do you need to check the code every time?
Voiceover: Notes are very important. Notes and documents do not conflict. They do not solve the same problem.
Sunshine positive energy:
Writing good documentation is good for yourself, for the project, and for the team. Why not do it?
3. The 
third point of view is: no time to write.
God is fair, time is conserved, spend more time thinking about the design, coding will definitely be smoother, can reduce a lot of communication / wrangling time, can save a lot of additional modification / joint debugging / testing time caused by program changes , Which can save a lot of time for long-term maintenance.
Sunshine positive energy:
I want to exercise, but I don't have time.
I want to learn English, but I don't have time.
I want to write a good document, but I don't have time.
I have time to browse Moments, headlines, vibrato, and chasing series. I have time.
Reject the excuses, act together, and write technical documents.
Fourth, 
there is another point of view: requirements change quickly, solutions change quickly, and documents are written slowly. Therefore, writing documents is useless.
When discussing a matter, first discuss the rationality. If it is reasonable but there are difficulties, then look at the difficult solutions. Normally it should be such a logic, right?
Because:
"Requirements change quickly, solutions change quickly, and documents are written slowly."
So:
"Writing documents is useless"
The logic itself is wrong.
We (especially the technical leader with the right to speak and make decisions) First of all, shouldn't we think about it:
- Demand is always changing, is it reasonable?
- The plan always changes, is it reasonable?
- Is it reasonable to write documents slowly?
- Is it reasonable to have no documentation?
Shouldn't you ask yourself these questions first.
If you think that “document writing is slow and unreasonable”, then, shouldn’t you think about
why the writing is slow? Is it due to insufficient willingness, insufficient ability of employees, poor use of tools, or other reasons?
- If the willingness is insufficient, how to increase the willingness of employees
- If ability is insufficient, how to improve staff ability
- If the tool is not good, how to optimize the efficiency of the tool
...
Existence may not be reasonable:
- "Slavery" has existed for thousands of years, so is it reasonable to be a slave?
- "Total demand changes, plans always change, and no documentation", but are these necessarily reasonable?
Sunshine positive energy:
As a technical leader, the brothers and sisters in your team are in dire straits, but you don't act. Don't you feel guilty? Please act within your own ability to try to change the unreasonable status quo and create a technological atmosphere.
V. 
One point of view: if others don't write, write by yourself, and lose money.
One point of view: the boss needs documents, the code farmers don’t need it.
One point of view: the salary is so low, don’t write it; if the salary is increased, write it.
One point of view: writing documents is to achieve others.
Voice-over: There are too many comments, so I won't release them one by one. Please refer to "How to write technical documents?" "Comment at the bottom.
An article "How to write technical documents? ", most of the points in the comments are "it's useless", which I never expected.
Voiceover: I hope everyone is just joking about me instead of thinking so.
Even, I think, what I have always insisted on, is it right?
In 2011, when I was transferred, I did a serious "module handover". I sorted out and summarized the 13 modules I was in charge of at that time. I was afraid that after I transferred, the engineer who took over might not be able to handle the project and the module, and I would feel extremely guilty.
Even a few months after the transfer, if the colleague who took over my module has questions, I will go to the colleague's desk to answer the colleague's question.
end:
Regardless of whether someone writes a document or not, I think this is the right thing, and I will do it.
Regardless of whether other leaders require documentation or not, in my team, I will do so.
After many years, perhaps you will find that it is precisely because you have made a choice that is different from others, you have become a different you from others.
mutual encouragement!
Architect's Road-Sharing Landable Technologies
related suggestion:
"How to write technical documents? "
The demand always changes, is it reasonable?" 》
Research:
Does your boss do anything unreasonable?