Some people think programmers don’t like to document because they don’t have great tools, but I think there are two main reasons software engineers don’t like to not document. First, writing is hard. Second, you can publish without documentation. Tools are only one of the few reasons.
First, writing is difficult
Writing is never easy. Software engineers, like everyone else, are reluctant to document because it is too hard to write clearly and succinctly. Writing is a very difficult task. We must organize our thoughts clearly, then examine and organize them, and finally express them clearly. Although the final presentation section can be simplified to some extent (depending on the quality of the writing), it takes a lot of effort to complete all three steps correctly. In the programming world, the best answer we can give to any question is, “It depends.” There are trade-offs, but writing is more complicated. You need to set context, justify the decision, and then demonstrate the driving force behind the underlying ideas in the code. Such documentation is useful only if it is well written, but it is so difficult that it is often impossible. Bad code still works, but bad documentation does not. That’s why there’s a lot of debate about the value of adding comments to code, and the benefits of code that can be used as documentation. Kevlin Henney argues that adding comments around complex code is practically futile, and if a developer can’t express himself clearly in code, how can you expect him to express himself clearly in English?
Second, you can publish without documentation code
Even if developers don’t document, they can still get their work done. The lack of documentation also doesn’t prevent delivering code (at least not right away). The damage caused by undocumented technical decisions is cumulative. Like technical liabilities, there is no immediate harm. As I said above, writing is mainly about thinking and analyzing. Most of the time, programming is all about experience and judgment. A jumble of code will work, but a jumble of words and paragraphs won’t make an article. Writing must be clear to work. As long as the code does the job, it’s acceptable (up to a point). Moreover, since most organizations only care about the delivery of the product, anything that does not impede the delivery of the product is ignored. On many teams, unit testing faces a similar problem. In order to test the code, we need to understand the code in the first place (and often spend more time than writing it), and the absence of testing does not hinder product delivery. So, great, there are no unit tests in the code. There is also the issue of obsolescence. Even well-written documentation becomes obsolete, so engineers must repeat the thought-analytic-expression process as they build systems. As a result, it’s easy to abandon documentation. As a result, we tend to cram until we need to write and organize documents.
Three, tools,
There is no doubt that there is a serious shortage of common tools to help us document software today. Instead of thinking about one document at a time, we put together multiple concepts and think about multiple ideas and goals. The final document is just a reflection of the thought process. We need tools to help us organize our thoughts to solve the problem at hand. Google Docs, Confluence, and Markdown are all such writing tools, but they don’t work very well. While tools have an impact, the unwillingness to take on the task is the real problem.
What about the documents?
Writing software taught me one thing. If you want your users to do something, you have to make it something they don’t have to do in the process of using your product. Similarly, if documentation is just an adjunct to code, no one will ever actively document it. Worse, the documentation isn’t very useful yet. Writing requires critical thinking. The purpose of documentation is to explain your thought processes and intentions to yourself and your audience, such as your team. This thought process is what documentation provides value, not well-written static text. Proponents of pair programming often disparage documentation. However, writing and reviewing technical documentation is the only way teams can form a unified understanding of the product they are building. This unified understanding is critical to the long-term health of the team and the code base. In my opinion, the only way to make documentation sustainable in the long run is to make it a hindrance to software development. Documentation should be part of the process. In my experience, the following methods may help.
Before you write the code, document it first. Unless the code changes are very minor, each engineer should write a note explaining what they are going to do, and the rest of the team should actually do it. After a thorough discussion, the actual code changes are trivial.
Simplify documentation. Don’t make your documentation too complicated. Bells and whistles like charts can wait. You simply write down what you think, what you do, and why. Even if the documentation only provides basic instructions for the rest of the current and future team, it is valuable.
Write down alternatives. Instead of documenting the actual implementation in detail (because implementations can change over time), you should focus on documenting why you chose a particular scenario. This is something the code can’t explain, so it’s valuable to document. You can devote a certain amount of time to recording the details, depending on the situation.
Easy to find. If people can’t find the document, it’s useless. You can use tools that support text search.
Record changes. Some organizations use version control to document changes in system design over time. If you don’t have one, keep a document for each feature and add the latest updates to it to keep track of all changes.
Finally, it is hoped that the team can gradually realize the value of documents in the process of creating and viewing documents, and develop the good habit of recording documents. But until then, you should treat documentation like a diet or diet, and stick to it painfully and joyfully.