How does a programmer write a good document?

In the actual software development work, in addition to writing code, programmers also spend a lot of time to write related research and development documents, including: Detailed design documents, unit/integration test documents, software version development reports, software Installation instructions, software upgrade instructions.
In the article "Programmers have to write good code and write good Documents" (http://www.zhouzhaoxiong.com/142.html), I mentioned that "code" and "documentation" are like a person's right hand, so be sure to make them balanced and not be one of them. Since the document is so important, how can we write a good document for programmers? In my personal experience, we may wish to start with the following:

first, the important content is described in a sub-point rather than a mixture.
For example, there is a description of a software feature:

该软件模块在系统中占有重要的地位，它从客户提供的FTP目录下获取文件，并下载到本地的目录中。接着，它扫描本地目录，对读取到的文件的内容进行解析，并生成新的文件放到本地的另一目录中。然后，它将该目录中的文件上传到客户指定的FTP目录中。对于本地目录中的文件，该模块有一个过期清理的机制，清理时间及过期期限可配置。

We can see that the above words put the SOFTWARE function description in a paragraph, read to let the reader foggy. We can describe the content in the following points:

该软件模块在系统中占有重要的地位，其实现的主要功能为：(1)从客户提供的FTP目录中下载文件到本地的目录中。(2)从本地目录中获取文件进行解析，并生成新的文件放到本地的另一目录中。(3)将目录中生成的文件上传到客户指定的FTP目录中。(4)清理本地目录中的过期文件(清理时间及过期期限可配置)。

After this modification, the logic of the article is more clear, more readable, the reader is more likely to understand the meaning of the author's expression.

second, the process of relatively strong content is drawn into a flowchart, rather than just the text description.
An illustrated article is a good article, if you see a good dozens of pages of the article is all text, it is easy to lose interest in reading. For some of the more process-strong content, if the text into a flowchart, the reader is not the same feeling.
For example, the following text describes the entire message flow of the socket:

第一步，创建socket。第二步，绑定指定的IP地址和端口。如果绑定失败，则跳到第一步。第三步，启动监听。如果没有监听到消息，则程序一直处于监听状态；如果监听到了消息，则执行下一步。第四步，循环从监听队列中获取消息，并根据消息内容执行相关的操作。

Draw the text into a flowchart as follows:

From the flowchart, it is easier to see the logic of the program, which allows the reader to understand the meaning of the author's expression in a relaxed reading journey.

third, the content with the numbers is presented in the form of a chart, rather than in a text description.
For some of the reference character of the number, we can be presented in the form of a chart, so that the reader can see the number of adjacent groups of changes, the article is better to express.
For example, the following paragraph describes:

今年3月份，解决的软件bug数量为8；今年4月份，解决的软件bug数量为6；今年5月份，解决的软件bug数量为10。

You can replace the above with the following chart:

, we are more likely to see the changes in the numbers before and after, and have a whole grasp of the things described.

Finally , try not to paste the code directly in the document, but in the form of pseudo-code, flowchart, etc.
Perhaps for the sake of convenience, many programmers like to paste the engineering code directly into the document, which not only takes up a lot of document space, but also reduces the readability of the document. Imagine a person who has never been in touch with code, how can you read the code you gave in the document? Even for experienced programmers, it's not always possible to see the program you've written out at a glance.
If you write the code really good, want to show others, then in the text can only give the design idea, flowchart, etc., and in the appendix to give the complete code.

The above several writing the document suggestion is oneself in the writing document process some experience, not necessarily all is correct, everybody may refer. Generally speaking, the writing of the document should follow the principle of simple and understandable, the most direct and clear way to express the author's own meaning.
Einstein once said: "Scientists should use the simplest means to reach their conclusions and to rule out anything that cannot be recognized." In other words, simplicity is beauty . This "simple" principle can also be applied to document writing and applied to all software development projects.

My public number: ZHOUZXI, please scan the following two-dimensional code:

How does a programmer write a good document?