Programmers have to write code and write good documents.

Whether the programmer should focus on document writing. This is a seemingly small but more important issue. The software includes documentation in addition to programs and data. Second, if programmers just write programs and can't describe their ideas properly and gracefully in a document, then it's really a "code farmer".

Recently, CSDN is holding the "CSDN Bowen Contest" event. I think some of the entries in this event are well-organized, fluent in writing and beautiful in language, mostly from the hands of programmers. I can't help but think of a question: whether the programmer should focus on document writing.

importance of writing documents

For software-related industries, in schools or units you may have noticed, in addition to the program to write, drawing a design, there is an important task is to write documents . Why do you write a document? Because we have to show the things we do, not only to show the peers, may also be shown to other posts on the staff to see, and even show to the user to see. If we just write programs and don't describe our ideas properly and gracefully in the documentation, then it's really a "code farmer".

I've noticed that it's really rare for colleagues around to write high-quality documents. Kai-Fu Lee in the "Top of the Tide" in the preface , said: "I know a lot of leading engineers, but have a strong narrative ability of excellent engineers, I know can be said to be rare." "It's true that my colleagues I know are very little able to express their ideas clearly in the documentation.

There are a few things that I remember deeply about writing documents:

We send and receive a lot of mail every day, I looked carefully, many of the contents of the message is not fluent, or have a lot of typos, or misuse or no punctuation. Many times, from a different point of view, an e-mail has a lot of different meanings, so that people do not know what it is to express a meaning, which greatly reduces the efficiency of the work. In addition to the code, the project also contains a large number of documents. Open most of the documents, see the first eye, I have these feelings: typesetting is not neat, the format is not correct, the statement is not fluent, a lot of typos. It is known that the author does not write the document carefully, and the expression and organizational ability of the statement is not strong. When the project team members discussed, almost all of them were talking about how to write the program, and did not mention how to improve the writing of the document. Everyone seems to agree that the responsibility of the developer is to write the program well, and everything else is second.

The traditional definition of computer software is that software is another part of the computer system that is dependent on the hardware, and the software includes a complete set of programs, data, and related documents. Note that the "related document" is mentioned here, and if the document is not written well, then the software is not considered to be a good software. In fact, the software function is sound, and due to the failure of the document causes the situation also occurs.

In general, in the software development process, the main documents involved in 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 phase, you need to write detailed design documentation, unit test scenario documentation, and integration test scenario documentation, and in the development phase, these documents are just revisions, as we will find in the actual development process that the previous design is unreasonable or poorly thought out, which requires modification of the previous document In the test phase, to write unit test report, Integration test report and System test report, etc., in the software release phase, to write installation manuals, user manuals, upgrade instructions, etc., these documents are mainly for the field support staff and users, so to write as easy as possible, do not have ambiguous circumstances exist, Otherwise, it will only wait for the user's complaint.

To write a good document, we need to first correct the idea that the document is not important. Place the document in a position that is equally important to the program.

How to write high quality documents.

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

Change the concept of a supplement to the document, in the ordinary work, for each of their own written documents, are treated seriously. For the writing of the message, you want to say the words accurately expressed, before sending the message, then look at the content is complete, whether there are typos, the statement is fluent and so on. In the process of writing the document, you should strictly refer to the template specified by the project team to complete. After you finish writing the document, check the document for syntax to correct typos and grammatical errors. Generally speaking, there is a wavy green line underneath the statement with the syntax error. Read through the entire document before submitting the document to see if there are any omissions or deficiencies. In addition to the work, you can read some books or articles that can improve the ability of language expression and writing, and see how others clearly articulate their thoughts. For example, it is a good way to improve your writing skills by reading the blog post of a csdn top blogger.

In general, as with everything else, writing a document also reflects a person's attitude. Writing high-quality documents can not only improve your personal image (if you see a good document, it is also highly rated by the author.) ), but also to enhance the product in the customer's heart image. So it's really necessary to spend more time writing documents.

To do a good job, we need to work from all sides. In the process of developing the software, it is important to write the code well, and it is also very important to express your thoughts clearly and in the document. "Code" and "documentation" are like a person's right hand, it is important to let the two balanced development, and not be able to only one.

Original link http://www.csdn.net/article/2014-08-12/2821148