How to write good technical documentation-more than ten years of documentation experience from Google

Most of the content in this article is translated and summarized from Chapter 10 _Documentation_ of "Software Engineering at Google". In addition, the electronic version of the book has recently been available for free download https://abseil.io/resources/swe_at_google.2.pdf , interested students can download and read it. First of all, not limited to plain text documents, but also contains code comments (comments are also a special form of document) .

Many technical people themselves despise the writing of technical documents, but they often complain about imperfect documents, poor quality, and not timely updates... This kind of common contradiction among programmers has even evolved into a paragraph.

The importance of documentation

High-quality documentation has many benefits for an organization or team. example, makes the code and API easier to understand and makes fewer errors; allows team members to focus more on the goal; it can also make some manual operations easier; in addition, if If new members join, having documents will also make them integrate faster...

Writing documents has a relatively serious income lag , unlike a test, you run a test case, it can tell you right or wrong immediately, and its value is immediately reflected. And write a document, with the passage of time, its value will gradually manifest. You may only write a document once, and it will be read hundreds or thousands of times in the future, because a good document can answer questions like the following for you in the future.

1. Why was this decision made at that time?
2. Why is the code implemented like this?
3. What are the concepts in this project?
4. ……

Writing documents also has great benefits for writers:

• helps you conceive a standardized API: The process of writing documentation is also the process of reviewing your API. When writing the documentation, you will think about whether your API design is reasonable and whether it is comprehensive. If you cannot describe the API in language, then your current API design is unreasonable.
• document is also another display of the code: example, if you look back at the code you wrote two years later, if there are comments and documentation, you can quickly understand the code.
• makes your code look more professional: we all have a feeling that as long as the well-documented API is a well-designed API, although this feeling is not completely correct, the two are indeed strongly related, so in many In the eyes of humans, the completeness of the document has also become an indicator of the professionalism of a product.

• avoid being disturbed by repeated questions: Some questions you only need to write in the document, so that when someone asks you, you can ask him to read the document directly instead of explaining it to him again.

  Why do most people dislike writing documents?

  Regarding the importance of documentation, every technical person knows more or less, but many people still don’t have the habit of writing documentation. Why? income lag of in the document mentioned above, there are the following reasons:

• Many engineers are used to separating code and writing, not only in their work, but also in their thinking that they are two completely unrelated tasks, which leads many people to emphasize code rather than documentation.
• There are also many engineers who think that they are not good at writing and simply stop writing. This is actually an excuse for being lazy. You don't need gorgeous rhetoric or vivid language to write a document. You only need to make the problem clear.
• Sometimes the poor use of tools can also affect document writing. If there is no good writing tool to embed writing documents into the development workflow, writing will indeed increase the burden of work.
• Most people see document writing as an extra burden of work. I don't have time to write code, how can I have time to write documentation! , this is actually a misconception, document although the initial investment there, but let the latter part of your code maintenance cost reductions , may quicken work this reason I believe we are still able to understand.

How to produce high-quality documents

Now that we understand the importance of good documentation, how can we ensure that we maintain a good document over the course of time? Here are some related methodologies. You can refer to it.

Manage documents like code

For how to write good code, the entire technology circle has a lot of experience summed up, such as the book "Refactoring" and "The Way of Code Conciseness"... For various programming languages, there are also related specifications, such as the foreign Google C++ specifications. The domestic Ali Java development specification etc... But there seems to be very little information about the documentation. But in fact, the document should not be separated from the code. You can simply and crudely think that the document is actually the code written in a special language, which is the language of humans. If you think about it this way, in fact, a lot of our experience in code and engineering can also be used directly in the document, such as:

• Have a unified specification
• Has version control
• Have a clear responsible person to maintain
• Review mechanism has been changed
• Questionable feedback and update mechanism
• Regularly updated
• Measurable indicators (such as accuracy, timeliness)

Know who your readers are

There is a very common mistake in writing documents, that is, many people write documents for themselves. In this case, your documents can only be understood by yourself or people with similar knowledge background. When the team is small This kind of problem is okay. You are all doing similar work, so you can understand the document. But as the team grows, problems will become prominent. Newcomers sometimes have different work backgrounds than you, and even now they are doing different work content. At this time, the documents you wrote before are difficult for them to read.

So before writing the document, please clarify who the possible readers of your document will be, and then focus on how to make them understand based on their characteristics. Of course, the document does not have to be very serious and perfect, as long as it can explain the problem to your potential readers. Remember that the document is written for others to see, not for yourself.

According to professional level, readers can be roughly divided into three types: novice, veteran, and expert. Writing for people of different levels needs to focus on writing. For example, for novices, you need to focus on the terms and concepts involved, and then explain the specific implementation in detail. On the contrary, you can omit this extra information for experts. Note that there is no strict standard here, because some articles will be read by novices, and experts will also read them. Here we still need to analyze specific situations.

Another way to categorize readers is to categorize readers according to their purpose of reading the document. For example, if someone knows what problem they have encountered, they come to find a solution. There are also a group of people who only have a simple idea, but don't know the specific problem. For example, take the slow reading of the database as an example. The former already knows that the slow database may be due to the huge amount of data and no indexing. The solution is simple to add the index. At this time, he may need to know how to add the index correctly. The latter may focus on why it is slow to read the database. At this time, you may need to focus on introducing the principles related to the database.

Clear classification

Documents can be roughly divided into the following types, each type also has its own different characteristics and writing focus.

Reference documents

Reference documents are also documents that most developers use and write on a daily basis. For example, if we use a certain framework or tool, there will be API documentation, which is a reference document. It was not too many requirements, as long as the reader can show clearly how use can, but do not need to explain to readers the implementation.

Note: Reference documents are not limited to API documents, but also include file comments, class comments, and method comments, all of which are required to accurately explain their usage.

Design document

Many companies or teams require design documents before the project starts. Design is the first step in project implementation. Therefore, it is required to be as thorough as possible in the process of writing design documents, such as the storage, interaction, privacy of the project...

A good design document should contain the following parts:

1. Design goals
2. Strategies implemented
3. Various trade-offs and specific decisions
4. alternative plan
5. Advantages and disadvantages of various solutions

The process of writing design documents is also the process of planning the entire project and thinking about possible problems. The more detailed the design and the more you think about, the less likely you will encounter problems in the future.

Guided documents

Guide documents are also very common, generally in the form of Step by Step For example, when we use a certain framework or tool, there will generally be a guide document to help you get started quickly. Everyone writes introductory articles. One mistake that everyone makes very easy is to preset a lot of background knowledge . Generally, the documentation for use is written by developers, and they all know the relevant knowledge of this tool very well, so it is habitual to think that is a very simple knowledge point, and users will definitely do . In fact, users may not. This is essentially a cognitive bias , which is also very obvious in cross-team collaboration, especially multi-end collaboration.

In this type of document writing, requires the writer to think from the perspective of the user as much as possible, try to avoid the cognitive deviation from the user, and strive to be clear and unambiguous for each step, and close between each two steps. Convergence.

Conceptual document

When the reference documentation cannot explain something clearly, conceptual documentation is needed, such as the specific implementation principle of an API. Its main purpose is to expand the reference document, not to replace the reference document. Sometimes this and the reference document will have some repetitions, but it is mainly for deeper explanation of certain issues and clear explanation of a certain concept.

Conceptual documents are also the most difficult to write and the least read of all documents, so in many cases, engineers are the easiest to ignore. And there is another problem. There is no suitable place to put it. The reference document can be written in the code, and the landing page can be written in the project homepage. It seems that the conceptual document can only be stored in an inconspicuous corner of the project document.

The audience for this type of document will be relatively wide, and both experts and novices will read it. In addition, it needs to emphasize that the concept is clear and clear, so it may sacrifice completeness (which can be supplemented by the reference document) or accuracy. This does not mean that accuracy must be sacrificed, but it should be distinguished between priority and unimportant. No need to say.

Landing pages

Landing pages were simply translated into landing pages first, but I didn't expect any proper translation words. For example, the navigation page of a team or project, although there is no specific content, should contain links to other pages. For example, if you join a new team, the more mature team will throw you a document. This document contains commonly used tools and document links. This is the landing page of the team.
The problem with landing pages is that as time goes by, the pages may become more and more chaotic, and some of the content will become invalid, but these problems are easy to solve, and regular maintenance and organization are enough.
The landing page is not technically difficult, but it requires the validity, completeness and clear classification of the content.

Document Review

In an organization, it is not enough to rely on individuals to maintain the documents. It must rely on the wisdom of the group. Within an organization, document changes should also be reviewed by others just like code changes, in order to discover the problems in advance and improve the quality of the documents.

How to review documents:

• professional perspective to ensure accuracy: generally responsible for the more senior people in the team, and their core point is whether the document is written correctly, professional or not. If Code Review does a good job, the review of the document is also a part of Code Review.
• reader's perspective guarantees simplicity: generally reviewed by people who are not familiar with this field, such as newcomers to the team or users of documents. This part is mainly concerned with whether the document is easy to understand.
• writer's perspective to ensure consistency: by someone with rich writing experience or a senior in related fields, mainly to ensure that the document is consistent, such as whether there is ambiguity in the use and understanding of the same professional term.

Philosophy of document writing

The above part looks at how to improve the quality of documents from the perspective of the organization and the team. Next, let's look at how to write high-quality documents from the perspective of individual writers.

5W rule

I believe you have heard the 5W rule a lot. They are Who What When Where Why. This is a rule that is widely used in all walks of life. Of course, it can also be used to write documents (5W rule can be called a panacea, and it can be used anywhere) .

• WHO: has been mentioned before, who is the document written for, and who is the reader.
• WHAT: clarifies the purpose of this document. Sometimes, just explaining the purpose and purpose of the document can help you build the framework of the entire document.
• WHEN: specifies the creation, review and update date of the document. Because the document is also time-sensitive, clearing the relevant date can prevent readers from stepping on the pit.
• WHERE: should the 160ffee4773ae1 document be placed! It is recommended that an organization or team has a unified permanent document storage address and version control. It's best to make it easy to find, use and share.
• WHY: write this document, and what do you expect readers to get from the document after reading it!

Three-phase writing

Writing an article generally has three parts. Professional writers also pay attention to crested head, pork belly, and leopard tail . These three words summarize the characteristics of the three parts of a good article. Technical documents can also be regarded as a kind of article, so generally there are these three parts, each part has its own role, such as first part explains the problem, the middle part introduces the specific solution, and the third part summarizes the main points. But this does not mean that the document should have three parts. If the document content is relatively large, it can be disassembled in more detail, and some redundant information can be appropriately added to help readers understand the content of the document. Although many engineers hate redundancy and strive for brevity, writing documents is different from writing code. Appropriate redundancy can help readers understand. It is very simple. For example, there are often examples in writing. Examples given are essentially redundant. For more information, vivid examples can definitely help readers understand abstract content (I think this is bootstrapping
Bar).

Conclusion

One of the better phenomena we have seen so far is that people are paying more and more attention to documentation, but they are not paying enough attention compared to testing. Testing is already an integral part of the workflow, and documentation is still not. Of course, this may be related to the characteristics of the document itself, the test is easy to be automated, and there are many objective indicators to evaluate. Documents can't be done. First, the writing of documents requires manual intervention, and the quality of documents does not have too many objective indicators to evaluate. Improving the quantity and quality of documents can only be gradually changed from the culture and workflow.

Finally, summarize the key points of this article:

• As time goes by and the size of the organization grows, documentation will become more and more important.
• Documentation should also be part of the development process.
• A document focuses on only one thing.
• The documentation is written for readers, not for yourself.