In most software engineers, writing 、 Complaints about using and maintaining code , A common problem is the lack of high-quality documentation . What are the side effects of lack of documentation ? When I meet a bug when , What does this abbreviation mean ? Is this document up to date ? Throughout his career , Every software engineer has complained about the quality of documents 、 Quantity or total lack of documentation .

01

Why do you need to write documents ？

High quality documentation is of great benefit to engineering organizations . Code and api Make it easier to understand . When their design goals and team goals are clearly stated , The project team will be more focused . When the steps are clearly listed , Manual processes are easier to follow . If the process is clearly recorded , Then it takes much less effort to get new members into the team or code base .

however , Because the benefits of documentation have a certain lag , It usually does not bring direct benefits to the author . Unlike testing , Write test cases , Run once and you'll get results . After all , You may have written only one document , But then it will be read hundreds of times , Even thousands of times ; Its initial cost will be amortized to all future readers . Documents can not only expand over time , And it is also critical to the expansion of other parts of the organization . It helps answer the following questions ：

• Why did you make these design decisions ?

• Why implement this code in this way ?

• Why most engineers don't like writing documents ？

Although documentation can bring many benefits , Why do engineers usually think it's bad ? One reason , As we mentioned , The benefits are not immediate , Especially for the author . In addition, there are the following points ：

• Many engineers are used to separating writing code from writing , Not just at work , And I think they are two completely unrelated jobs , This leads many people to focus on code rather than documents .

• There are also many engineers who think they are not good at writing , Just don't write . This is actually an excuse for laziness , You don't need fancy words to write documents