Go homepage(回首页) Upload pictures (上传图片) Write articles (发文字帖)
The author:(作者)aaapublished in(发表于) 2014/8/12 2:39:25 Code： writing good code and written document，
Code: necessary to write good code, and written documents-programmer, code, code, document-IT news Code: necessary to write good code, and written documents
Summary: whether programmers should pay attention to the document prepared? This is a seemingly small but important issues. Besides programs and data, software, including documentation. Second, if programmers only write procedures, cannot properly and elegantly described in document their thoughts, then there really is "code rural".
Whether programmers should pay attention to the document prepared?
The importance of written documents
For software-related industries, at school, or you may have already noticed, in addition to the program to write, draw, design charts, there is another important task is to write the document. Why write documentation? Because we have to do their own thing displayed, showing not only to peers, staff may want to show to other positions, even displayed to the user. If we just wrote the program not properly and gracefully in a document describing one's own ideas, then become a true "code rural".
I note a bit, does very little of the surrounding colleagues will write a high quality document. Kai-Fu Lee, a teacher in the preamble of the top of the tide, said: "I know a lot of top engineers, but there is a powerful narrative ability of outstanding engineers, I know, can be said to be rare. "It is true that the colleagues I know and be able to articulate their ideas in the document is very small.
Related document writing impressed me question has the following aspects:
We are receiving a lot of emails every day, I carefully looked at, lots of e-mail content or statements are not fluent, or have a lot of typos, misuses or no punctuation marks. Most of the time, from a different perspective, a message that has many different meanings, make people feel does not know what it wanted to express a meaning, which greatly reduces the efficiency of the work.
In addition to the code, the project will also include a large number of documents. Open most documents, seeing at first glance, I have these kinds of feelings: writing is not neat, not in the correct format, statements not fluent, pretentious English. An eye that the authors did not write the document and the statement of strong communication and organizational skills are not.
At the time of project team members to discuss, and almost all of us were talking about how to write programs, but there is no mention in the document writing should do to try to improve. Everyone seems to agree that the developer's job to write programs, and everything else is secondary.
Traditional computer software is defined as: software and hardware is a computer system depends on another part of the software including programs, the complete set of data and its associated documentation. Note that this refers to "related documents", if the document is not written, the software can not be regarded as excellent software. In fact, the software features sound, but because the document cause fail still appears occasionally.
Generally speaking, in the process of software development, main document involved at different stages as shown in the following figure:
Can be seen in different stages of the software, you need to write a different document. In plans stage, needs prepared detailed design document, and unit test programme document and integrated test programme document,; in development stage, is this several document, just amendment version, because we in actual development process in the, will found zhiqian design not reasonable of place or is considered poorly of place, this on needs on zhiqian of document for modify; in test stage, to prepared unit test report, and integrated test report and system test report,; in software of released stage, to prepared installation manual, and user manual, and Upgrade instructions, which are primarily for field support personnel and users, it will try to write more accessibly, never ambiguity exists, otherwise it only waits for user complaints.
If you want to write good documentation, we need first to correct the idea that documents are not important. Where you want to put your documents and programs are equally important.
How to write a high quality document?
So, how do we produce high quality documentation? I think we can proceed from the following aspects:
Change document, supplemented by the concept in everyday work, for each document you have written, seriously.
For messages written to accurately express what they want to say, in the message before you send it, then see if the content is complete, if there are typos, such as whether a statement is clear and coherent.
In the process of preparing a document, it closely follows the project team provided a template to complete. After you finished writing the document, grammar check on a document to correct typos and grammatical errors of the place. Generally speaking, the statement that there is a syntax error will have a green squiggly line under it. Before the document is submitted, and then read through the entire document to see if there are omissions and deficiencies.
In his spare time, you can read to improve language skills and ability to write books or articles, take a look at how others are articulating his thoughts. For example, often reading CSDN excellent blogger's blog is a good way to improve your writing skills.
In General, and do other things, like writing document also reflects an individual's attitudes. To produce high quality document, can not only improve their image (if you see a good document, is also the author has a higher rating? ), As well as to enhance the image of the product in the minds of customers. Such analysis and spend some effort to write the document really is necessary.
If you want to do one thing, we need efforts from every aspect. In the process of developing software, writing good code is important, clearly express themselves clearly in the document are also very important. "Code" and "documents" looks like a man who's right-hand man, be sure to keep the two balanced development, rather than just one or the other.
赞