Should programmers pay attention to documentation writing? This is a seemingly small but rather important issue. In addition to programs and data, software also includes documentation. Furthermore, if a programmer can only write programs and cannot appropriately and elegantly describe their ideas in documentation, then they truly become a "code farmer."

The Importance of Writing Documentation

In software-related industries, whether at school or in the workplace, everyone may have noticed that in addition to writing programs and drawing design diagrams,there is another important task: writing documentationWhy write documentation? Because we need to show what we have made—not only to peers, but also to staff in other positions, and even to users. If we can only write programs and cannot appropriately and elegantly describe our ideas in documentation, then we truly become "code farmers."

I noticed that very few of the colleagues around me can write high-quality documentation. Mr. Kai-Fu Lee, in "The Wave"'spreface,said: "I know many top engineers, but excellent engineers with strong narrative skills are, among the ones I know, extremely rare."

Indeed, among the colleagues I know, very few can clearly express their ideas in documentation.

1. We send and receive many emails every day. I looked carefully and found that the content of many emails either has awkward sentences, contains many typos, or misuses or omits punctuation. Many times, an email can be interpreted in many different ways, making people feel unclear about what it is really trying to express, which greatly reduces work efficiency.
2. In addition to code, projects also contain a large amount of documentation. When I open most documents, the first thing I feel is:Messy layout, incorrect formatting, awkward sentences, and typos everywhere.At a glance, you can tell the author did not take the document seriously, and their ability to express and organize sentences is also weak.
3. During project team discussions, almost everyone talks about how to write programs well, but no one mentions how to improve documentation writing. Everyone seems to agree that a developer's duty is to write programs well, and everything else is secondary.

The traditional definition of computer software is: software is the other part of a computer system that is interdependent with hardware. Software includes the complete collection of programs, data, and related documentation.Note that "related documentation" is mentioned here. If the documentation is not well written, the software cannot be considered excellent. In fact, there are cases where software functions are sound, but failures occur due to documentation issues.

Generally speaking, in the software development process, the main documents involved at different stages are shown in the following figure:

It can be seen that different documents need to be written at different stages of the software. In the planning stage, detailed design documents, unit test plan documents, and integration test plan documents need to be written; in the development stage, these same documents are still needed, but as revised versions, because during actual development we may discover unreasonable or poorly considered parts of the previous design, which requires modifying the earlier documents; in the testing stage, unit test reports, integration test reports, and system test reports need to be written; in the software release stage, installation manuals, user manuals, upgrade guides, and so on need to be written. These documents are mainly aimed at field support personnel and users, so they should be written in an easy-to-understand manner, and there must be no ambiguity whatsoever; otherwise, you can only wait for user complaints.

To write good documentation, we first need to correct a misconception: that documentation is not important. Documentation should be placed on an equal footing with programs.

How to write high-quality documentation?

So, how can we write high-quality documentation? I think we can start from the following aspects:

1. Change the idea that documentation is secondary. In daily work, treat every document you write seriously.
2. For emails, accurately express what you want to say. Before sending an email, check whether the content is complete, whether there are typos, and whether the sentences are fluent.
3. When writing documents, strictly follow the template specified by the project team. After finishing the document, run a grammar check to correct typos and grammatical errors. Generally speaking, sentences with grammatical errors will have a green wavy underline beneath them. Before submitting the document, read through the entire document again to see if there are any omissions or shortcomings.
4. In your spare time, you can read books or articles that improve language expression and writing skills, and see how others clearly articulate their thoughts. For example, regularly reading blog posts by excellent bloggers on CSDN is a good way to improve your writing ability.

In general, like doing other things, writing documentation also reflects a person's attitude. Writing high-quality documentation can not only enhance your personal image (if you read a good document, wouldn't you also have a higher opinion of the author?), but also enhance the product's image in the minds of customers. With such an analysis, it is really necessary to spend more effort on writing documentation.

To do something well, we need to work hard in all aspects. In the process of developing software, writing good code is important, and clearly expressing your thoughts in documentation is equally important. "Code" and "documentation" are like a person's left and right arms; both must develop in a balanced way, and we cannot focus only on one.

From:CSDNAuthor: Zhou Zhaoxiong