About the compilation of technical documents

From: http://www.cnblogs.com/ansiboy/archive/2013/03/11/2953988.html

There are a lot of articles on programming in the blog, but I have never seen anyone who has published this article, or some of them, I don't know? However, it is undeniable that the documentation is extremely rare. Is this related to the programmer's insufficient attention to document writing.

As a programmer, I made such a mistake and did not pay enough attention to writing documents. However, for a long period of contact with customers, it is extremely important to discover the writing of documents. Excellent documents can definitely add to your software and reduce the time spent on technical support for customers. Now, let me talk about some of my experiences in writing documents. A document should be composed of the following parts:

Document Composition

1. Software Overview. This part of the content should clearly describe the features of the software, so that users can know what functions and purposes your software has. What is it for their work or life. This part of content should be concise and clear and clearly described. It allows users to determine whether the software is what they want within one minute. It is best to match the software to give users an intuitive understanding of your software.

2. Use Authorization. This is an essential part. You must be clear about how you authorize the copyright of the software you write. You must tell users what restrictions they have on using your software. In general, it is better to use common protocols, Because I estimate that no user is willing to spend too much time to carefully read your authorization meanings.

3. Quick Start. In this article, you should teach users to use your software. It is best to set the time to within three minutes. Otherwise, the user can easily give up. The purpose of this part is to let users know more about your software and attract users to actively use it. Therefore, this part of content should be the most important, and the simplest, which best reflects the features of your software.

4. reference. The more detailed the content, the better. Describe all your software and functions. This part of content allows users to fully master the use of software.

5. FAQs. In this section, we should list some of the most common problems of users. You can quickly find the solution to your problems.

6. How. This part should list some common tasks and teach users how to use your software step by step. You can call this part step by step. This part is included in the Quick Start section.

The preceding sections are common documents. Next, let's talk about writing the document. A good document, at a glance, needs to have a pleasant feeling.

Document compilation

1. Documents must be indexed, that is, directories. This is very important because it can help users quickly locate the inner spaces they are interested in.

2. The layout should be beautiful. In my personal experience, the title must be centered and multiple Subtitles must have serial numbers. The interval between segments is moderate. Cannot be all in one partition; otherwise, reading may be affected.

3. the font size should be clear and easy to see. Simply put, you can get to know the structure of this chapter at a glance. Which part is the title, which part is the abstract, which part is the content, which part is the example, and which is the keyword. These may be reflected by the font size, bold, italic, and underline. In addition, the font of the body content should not be too small. Otherwise, reading for a long time may make the eyes tired. Generally, I use the font No. 5.

4. the font size should be uniform. That is to say, the title, title, content, and other fonts are consistent in size in each chapter. It cannot be said that the title of some chapters is in font 3, and the title of some chapters is in font 4.

If you are interested in writing the document, you can go to the http://esql.codeplex.com to download alinq dynamic to see, it contains a Chinese document, basically according to the above mentioned to write. The introduction to alinq dynamic can be found in this article? Spring also exists for LINQ to SQL! .

If you think this article is useful or enlightening, click here for support. Encourage me to write more high-quality articles.