Why don't programmers write documents?

Why don't programmers write documents? Don't you want to write? Recently, senior software engineer Kislay Verma analyzed the underlying reasons behind it.

He believes that software engineers do not write documents for the following two main reasons.

Writing is too hard

Like everyone else, the reason software engineers don’t write documents is that writing is very difficult.

Writing itself is a demanding task. It requires the writer to organize his ideas clearly, think critically, and finally express it clearly.

In the programming world, everything such as the best answer is based on a certain degree of trade-offs, which makes writing more difficult. When writing, programmers need to explain the background first, prove the correctness of the decision, and then introduce low-level thinking into the code. This type of writing is often very useful if done well, but it is not easy to do well, and sometimes it is even difficult to just complete the writing. Bad code can still run, but bad documentation won't.

This is why many people argue about the value of code comments and self-documenting code. Kevlin Henney, the author of "97 Things Programmers Should Know" once said, adding comments to complex code is futile and can't be expressed clearly in the code. How can it be expressed clearly in words?

Not writing documents does not affect the development process

Developers do not write documents and do not delay the work process, at least not immediately bring any negative effects. In fact, the impact of not documenting technical decisions is always accumulating.

Writing is a matter of thinking and analysis. In most cases, writing code can cross the river by feeling the stones. Poorly structured code may also work, but the indiscriminately piled up text and paragraphs are difficult for people to read. Writing must be clear to be useful. And the code can be accepted (to a certain extent) as long as it can run. Since most organizations only focus on how to make the product advance, things that will not affect the development process are of course ignored.

In many teams, unit testing also faces similar problems. To test the code, we need to understand it first, but this is more labor-intensive than writing the code, and the absence of unit testing does not affect the work process. As a result, many teams do not pay attention to unit testing the code.

There is another problem: obsolescence. Even good documents will be outdated, so engineers must constantly repeat the process of "thinking-analyzing-expressing" when building the system.

In short, it is too easy to give up writing documentation.

If a worker wants to be good at his work, he must first sharpen his tools

There is no doubt that the tools currently used for document writing are not enough. We don't think about the problem from the perspective of the document, but from the perspective of the idea and the goal, we piece together several concepts at once. The document is a reflection of the thinking process, and the quality of the document formed in this way can be imagined. We need some tools to help us sort out ideas at different times, and then solve the problem at hand. For this type of writing, Google Docs, Confluence, and Markdown are not enough.

However, a new generation of tools (such as Notion, Roam) is solving the problem of "networked thinking". These tools help turn thinking into documents.

However, lack of tools is by no means an excuse for not writing. The tools are certainly useful, but whether they have the willingness to write is the key to the problem.

How to write a document?

Kislay Verma said: "Writing software taught me one thing. If you want users to do something, you must make it an essential step in the process of using the product." The same goes for writing. Using documentation as an embellishment of code will not work, or even useless.

Writing is about critical thinking and requires you to explain the thinking process and intentions to yourself and your readers. thinking process adds value to documentation/writing, not just statically recording the code that has been implemented.

Proponents of Mob programming/pair programming and extreme programming usually despise document writing. But in addition to those types, writing and reviewing technical documents are the only way for the team to understand the products they create together, which is critical to the long-term healthy development of the team and the code base.

original text of https://kislayverma.com/programming/why-programmers-dont-write-documentation/