Notes for writing Technical blogs

I personally think that writing a blog (blogging) is the best way to summarize the technology. It can even be said that a blog is accumulation, and it is soy sauce from a certain perspective. It may be due to the habit of being constrained by specifications. I feel that I have some precautions when writing a blog. Although I have written many articles before, I feel that they are not very standard. Now I want to summarize the notes that should be paid attention to when writing a blog, to remind you at any time.

1. Do not repeat documents. Link to it should not repeat the document. Just give the link. Focus on your own experiences, experiences, and summaries.

There is no need to repeat the things that are clearly stated in the official documents, so we can provide the corresponding links. Especially for official documents such as msdn, it is better not to repeat the content, because you are not necessarily clearer than the official ones. The focus should be on your own experiences, experiences, and summaries. In this way, you can truly sum up and accumulate your experiences and turn them into experiences. It is also a valuable reference for others.

2. Make a comprehensive summary

As mentioned above, do not repeat the document. What should I write? I think it should be my summary after practice:

• Let's talk about all the reliable methods;

• Let's talk about the precautions;

• Compare various methods and give their respective advantages and disadvantages and applicable occasions;

• Situations that are not described in the document, such as supplement to the document, or conflict with each other.

3. verification must be performed in person to ensure reliability and feasibility. Attach the instance (source code, resource) and running result (etc.) 4. summarize valuable network materials related to the content discussed 5. list references, such as official documents, blogs of others, and source code. This is respect for others and knowledge. 6. You can refer to and reference it, but do not copy it. The most important thing is to have your own thoughts and understandings.

If it is inspired by others' blogs or code, it is best to reference key sentence paragraphs and then write your own thoughts and discussions. Give a link to the original text or source in the article to show respect and professionalism.

7. It is best to have version control information and revision records

We have a version control system for the code to help maintain the modification records. However, we recommend that you do this for documents. For blogs, there may be no (or I don't know) similar tools, but you can manually describe them. For example, add a revision history record to the header or tail of a blog, or mark the later modification in another font in the document, or use parentheses or footer to indicate the change. In this way, you can easily see your own thinking and growth processes.

8. less but better profound principles

The more detailed the lecture, the better the scope, and the smaller the scope, the better. But for more details, the ten-percent explanation is better than one hundred percent. If you can't explain it in depth, it proves that you have not been writing yet. You should study or practice it again until you can make it clear and give a detailed explanation, I will summarize and write a blog later. Strive to make an article a point, so that the article becomes no vulnerability in the end.

9. highlight themes, distinguish between primary and secondary, clear logic, and clear Layers

This may be a general requirement for writing, which is easy to say but difficult to do. In fact, it is not difficult, mainly manifested in:

• List of things to be discussed
• Use the title to give a concise summary, and then explain in detail
• The title and body are identified in different font styles
• The title and body are identified by font and indentation.

Is there a feeling that this seems to be about coding standards? Yes, it has been said for a long time that writing articles is the same as writing code. As a programmer, we can consider writing articles by writing code, including habits and specifications.

10. Read it several times after writing it, and make a correction.

This is like debugging and testing after writing the code. Good code is changed, and so is a good article. There are few people who can achieve it overnight. Even big writers like Lu Xun still need to modify their articles, but they haven't made them any more. What's more about us? After writing the article, debug and refactor the article as needed until you are satisfied and comfortable reading it. Imagine if I don't want to read any of my articles, will anyone else read them? We are not doing our homework. Good or bad teachers always look at it, and we should take a closer look. To write a good article, you must first consider it a good article.

11. use plain and easy-to-understand languages to explain the terminology

Good technical articles should be very easy to understand, even if you have no idea about the science you mentioned. Read the original English version of classic books such as "code complete", and you will find that reading the original version does not require any Nb-level English, anyone who has been to college should be able to understand it. In fact, the focus is not on understanding English, but on whether the author can express things clearly in the most understandable language. This is indeed a kind of ability. Our so-called communication ability is basically here to see if you can clearly express things in the simplest language and let the other party understand.

Here are some tips:

• This is the easiest way to understand. For example, compare software building to building a house, and compare software architect to a building designer.
• Use multiple diagrams. Most of the time, a chart can be used to cover hundreds of characters, but it is not necessarily clear. Everything is clear when you give a picture.
• Illustrated images and texts are the best way to explain them. Reasonable Picture Arrangement and text descriptions can get twice the result with half the effort.

12. Speak with facts

There are pictures, truth, and code, and truth. After that, I have talked about it. It is best to attach a real example, code, and. Otherwise, others may question the question. At least I will question the question when I see that others only "say" and "Do not.