Let you know about software development in advance (40): Both code writing and documentation writing are required.

Source: Internet
Author: User

Part 1 software R & D work summary

Both the code and the document must be written.

 

For software-related industries, you may have noticed that in addition to programming and drawing design drawings, there is also an important taskWrite document. Why write a document? Because we need to show what we do not only to our peers, but also to our staff in other positions, or even to our users. If we only write programs and do not describe our own ideas in the document, then we will truly become a "Code farmer.

I have been working for a while. I found that few colleagues around me can write high-quality documents. 

I am very impressed with the writing of documents in the following aspects:

(1) We send and receive a lot of emails every day. I have read carefully that the content in many emails is either not fluent or contains many incorrect characters or misuse or without punctuation marks. Many times, from different perspectives, an email has many different meanings, making people feel unaware of what it means, which greatly reduces the work efficiency.

(2) In addition to code, projects also contain a large number of documents. Open most of the documents, and at first glance, I have the following feelings:Incorrect layout, incorrect format, incorrect statements, and incorrect characters. At first glance, we can see that the author has not carefully written the document, and the statement expression and organization capabilities are not strong.

(3) During the discussion by project team members, everyone was talking about how to write the program, rather than how to improve the document writing. Everyone always thinks that the developer's responsibility is to write the program, and everything else is the second.

The traditional definition of computer software is as follows:Software is another part of computer systems that depend on hardware. software includes a complete set of programs, data, and related documents.. Note: "related documents" are mentioned here. If the documents are not written, the software cannot be regarded as excellent software. In fact, software functions are sound, and faults may occur from time to time due to document reasons.

Generally, the main documents involved in different stages of software development are shown in:


Figure 1 main documents involved in different stages of Software Development

It can be seen that different documents need to be written at different stages of the software. In the design phase, you need to write detailed design documents, unit test solution documents, and integration test solution documents. In the development phase, these documents are justRevisionBecause in the actual development process, we will find that the previous design is unreasonable or the design is not well considered, which requires modification of the previous document; in the testing stage, unit Test Report and integration test report should be prepared. In the software release stage, installation manual, user manual, and upgrade guide should be prepared, these documents are intended for on-site support staff and users. Therefore, they should be easy to understand as much as possible. Do not be ambiguous. Otherwise, they will only wait for user complaints.

 

In software product related documents, detailed design documents are very important. The detailed description of the design concept not only provides the necessary foundation for coding of this module, but also provides some reference for testers.

Generally, the content of a complete detailed design document consists of nine parts as shown in 2.


Figure 2 subject content of a complete, detailed design document

 

The integration test plan (Procedure) document is used to guide the integration test of software and is also a very important document.

Generally, the subject content of a complete integration test plan (Procedure) document should include 6 parts as shown in 3.


Figure 3 main content of a complete integration test plan (Procedure) Document

 

To write a document, we must first correct the idea that the document is not important. Documents should be placed at the same important position as programs.

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

(1)Change the concept of document Supplement. In normal work, every document you write is taken seriously..

(2)For writing emails, you need to accurately express what you want to say. before sending the emails, check whether the content is complete, whether there are typos, and whether the statements are fluent..

(3)In the process of writing documents, you must strictly follow the template specified by the project team. After writing the document, check the syntax of the document to correct the typos and syntax errors.. In general, there is a green wave line under statements with syntax errors. Before submitting the document, read the entire document to see if there are any omissions or deficiencies.

(4) In addition to work, you can read books that can improve your language expression and writing skills and see how others express their thoughts. 

 

In general, writing documents also reflects a person's attitude, just like doing other things. Writing high-quality documents not only improves your personal image (if you see a good document, do you also have a high rating on the author ?), It can also improve the product image in the customer's mind. Therefore, it is really necessary to spend more time writing documents.

To do one thing well, we need to work hard in every aspect. In the process of developing software, writing code is very important. It is also important to clearly express your thoughts. "Code" and "document" are like a person's right arm. They must develop in a balanced manner, rather than simply focusing on one.

 

 

 

 

(My microblogging: http://weibo.com/zhouzxi? Topnav = 1 & WVR = 5, No.: 245924426, welcome !)
Related Article

Contact Us

The content source of this page is from Internet, which doesn't represent Alibaba Cloud's opinion; products and services mentioned on that page don't have any relationship with Alibaba Cloud. If the content of the page makes you feel confusing, please write us an email, we will handle the problem within 5 days after receiving your email.

If you find any instances of plagiarism from the community, please send an email to: info-contact@alibabacloud.com and provide relevant evidence. A staff member will contact you within 5 working days.

A Free Trial That Lets You Build Big!

Start building with 50+ products and up to 12 months usage for Elastic Compute Service

  • Sales Support

    1 on 1 presale consultation

  • After-Sales Support

    24/7 Technical Support 6 Free Tickets per Quarter Faster Response

  • Alibaba Cloud offers highly flexible support services tailored to meet your exact needs.