[All-round analysis] How to write a good technical article

foreword

why write

Technological growth : Compared with the huge knowledge system in the computer field, human memory is still too limited, and with age, memory will also gradually decline. As the saying goes, "a good memory is not as good as a bad pen." And in the process of sharing blogs, we can also communicate with the great gods, and then discover our own cognitive errors and correct the knowledge system. The last and most important thing is that by recording blogs, we can summarize in time, sort out ideas through writing, and check for omissions.
Increase Influence : In today's world, if there is one thing that is most valuable to talk about, it is influence. The reason why Internet celebrities and celebrities can make a lot of money is because they have huge influence. In this era of fierce competition, those with strong influence are the real winners. And writing is undoubtedly a tool to expand influence.
Job opportunities : In the job hunting process, the role of blogs should not be underestimated. The blog itself is a very good platform for self-presentation. By showing the breadth and depth of your skills to the interviewer, you can be one step ahead of most job seekers .
Additional income : Rent advertising space on your own blog/official account, or place advertisements within the company, or sign a contract with a writer on a writing platform, or write and sell books with the help of influence

1. Clarify your own technical positioning and audience

The first is to clarify your own technical positioning . For example, if I specialize in front-end technology, then the technical topic selection of the blog should also focus on this direction, so as to create a personal IP. Here, by the way, the topic selection

There are many topics for technical articles , which are roughly divided into the following categories:

Evangelism on new approaches/techniques : like new JS features, or new build tools, etc.
Summary of technical solutions : such as loading optimization mechanism in a weak network environment, etc.
Experience guide for excellent frameworks : such as the process of react SSR from 0-1, etc.
Tips that I think are very powerful : such as some unique optimization methods, JS black magic, etc.
Principle analysis class: such as XXX diff principle, etc.
Solutions to difficult problems : such as the solution to CDN being hijacked

Among them, the first 3 points are more suitable for novice students to start, and you can start from these points according to your actual situation. You can find new technology points from caniuse

Secondly, the purpose of writing and the audience should be clarified. That is to say, set the tone of the blog post, whether it is light-hearted and humorous, strives for details, serious, professional and general, or other styles.

See it for yourself , it is just an essay, a personal note. It can be written casually, or even a sentence or a picture. It can be a self-proclaimed article.

For technology sharing , it is necessary to consider comprehensively at this time. It cannot be written as a self-proclaimed article. It must have a certain routine and clarify which groups the audience is, whether it is a novice, a master, or a leader. Play appropriately according to the preferences of the audience and your own circle of competence.

When requesting a draft , in general, Party A will give a certain format and requirements, and then combine the experience of technology sharing to complete the draft.

Self-healing article: Internet buzzwords are articles written with a high tone and gorgeous rhetoric, but they are not written from the standpoint of users.

2. Choose the right writing platform

CSDN : The oldest blog forum in China, the seo is doing very well, the number of users is large, but the quality of the articles is generally not high, and there are many advertisements, the user experience is not good
Blog Garden : Like CSDN, it is an old-fashioned blog site with good seo and many high-quality blogs, but the writing experience is poor and the style is old (but it can be customized and beautified)
Nuggets : The platform is new, the writing experience is great, the interface is refreshing, and the official often releases activities to provide material rewards for outstanding writers
Tencent Cloud/Alibaba Cloud Community : Daniel special session, the quality of the article is not to be said, but it is not very suitable for novices
Zhihu/Jianshu : Neither platform is a specialized technical website, but the quality of the articles is relatively good, and the SEO weight is high, which can be suitable for drainage
Public account : mainly to divert traffic from other platforms, suitable for long-term operation
Independent website building : relatively troublesome, but relatively free, it needs to be optimized for seo, Daniel blog: Zhang Xinxu , Ruan Yifeng , Liao Xuefeng

3. How to title the article

On average, 5 times more people read headlines than body text - David Ogilvy

In fact, there are two main importance of the title, one is SEO (search engine) optimization , and the other is to improve the reading experience of readers.

Key points of the title

1. Simple

I've read discussions about article titles that generally agree that article titles should be simple, short, and easy to understand. If you violate this principle, you can also get attention, that confused, overwhelmed attention. Short titles are also good for SEO—keep titles shorter than 40 characters to ensure they all appear in search results.

2. Attract attention

A good title can make your article stand out and attract readers to read it. Attracting attention can be achieved through the use of words that create a "shock", "appeal", "surprise" or even "confuse" effect. These words can attract readers to read the main text, even though it may be that the title party's text does not fit the title. Use headlines to attract readers as much as possible, even if it is a little trick.

3. To meet the needs

Good headlines get readers into the body of the text simply because they think there is content that meets their needs. A survey by the index website http://del.icio.us shows that the titles that attract the most readers are usually articles such as "How to..." or "Tutorials for..." because they want to solve the related problems they encounter .

4. Intuitive

Although many readers will be drawn into the main text by those ambiguous titles, most readers prefer intuitive titles so that they can decide whether to learn more. The title should be short and intuitive to indicate the main content of the text.

5. Keywords

Earlier in this article, I mentioned the importance of titles for SEO, so if you want to make full use of this effect, you need to think about how to choose keywords that are easier to attract attention. It may seem difficult to have a title that is both concise and compelling, but it can be done. For example, in SEO, the phrase in front of the title is more effective than the phrase in the back.

Supplement: How to write an introduction/abstract

The job of the heading is to get the reader to start reading the first sentence . The task of the beginning of the article is to attract readers and make them continue to read your article .

The introduction at the beginning follows the APP formula , that is, matching requirements ( A lign), display ( P resent), effect proof ( Proof ), examples

First, we match the requirements ( Align ). In 1-2 sentences, show your users that you understand the problem they are facing.

Next, present your article as a solution.

Inform them that you have discovered a solution to the problem. Or explain the method as briefly as possible without giving away everything . "Feed" people content so they can keep watching.

Finally, our proof of effect ( Proof ) is given.

Here you can explain why they should trust you. After all, chances are your visitors are viewing your blog or personal website for the first time. You have to demonstrate your success, experience and expertise.

4. Build the framework structure of the article

Sometimes I can't continue writing while writing. If you set up the framework in advance and make a mind map , it will be much easier, and you will not get stuck halfway through the writing. The general structure of technical blogs is total-point-total . The following are some templates I use to share, and they can be used as an example. If you have other templates, you may wish to share them, and we will make progress together.

Ask questions->analyze problems->solve problems->summarize experience and share technical problems.
Background->thinking->attempt->difficulties encountered->solution->final result, problem sharing
Abstract->Introduction->Branch Topics->Summary, general technical sharing.
What-Principle-Background>What Problems Are Solved->Basic Operations->Similar Comparison->Summary, suitable for sharing new technologies

5. Make pictures and related materials

draw.io : An online drawing tool, very powerful, with built-in various commonly used elements and icons.

excalidraw : An open-source drawing tool in the form of hand-drawing. You can draw pictures directly on the website without logging in. You can easily export files. After exiting and re-entering, it will also display the picture drawn when you exited last time. Import modules drawn by others. But it does not support Chinese handwriting, here is the URL that supports Chinese handwriting

6. How to write more attractive content

easy to read

No one likes to read. They just want information. If they can download this information into their brains, they will. ——Tim Soulo

The first thing we have to do is how to make our articles easy to read. I recommend Bond Halbert's book The Halbert Copywriting Method Part III. The following is a brief summary

**Use short paragraphs. **Bond says this provides "eye relief." Lots of text can deter readers, but short paragraphs can invite them in. Tools like Hemingway can make it easier.
** Break down long sentences. **People usually read to the voice in their head. Therefore, long sentences can make reading difficult to follow. Break down sentences by finding the real columns where "and", "because", and "this" are used.
** Insert multimedia. **Videos, pictures, animations, etc. can help you explain your point of view without adding text.
Use text format. Bold, italics, quotes or lists to break up large amounts of content and can emphasize specific points.
Read your essay aloud. This helps you spot things that aren't flowing or boring.

Form of expression

A technical article is not necessarily an argumentative essay or a narrative essay, and more forms of expression can be explored

Comics, such as programmer Xiaohui, are humorous and very immersive
WeChat/DingTalk chat box class, reading experience is also good
Fan fiction, such as "JavaScript: Immortals"
Sui Sui read the article, similar to Zhang Xinxu's article style, this kind of article can also play a very good effect with some daily jokes

empathy

After writing an article, it does not mean that your article can be published or promoted, because we write more from our own subjective point of view, so in order to ensure the readability of the article, you can also Think about it from the following perspectives:

If I am a novice, can I understand this article?
Can I understand the article if I don't recognize the acronyms in the article?
Do I want to add an architecture diagram here to explain?
Do I want to add a demo picture here to show it?
Should I add code comments here, what if the other party is a beginner?
…

At the same time, there is another very important skill, which is to read your own articles several times, read it when you wake up in the morning, and read it before going to bed at night. Maybe as you read it, your inspiration comes again, and at the same time you can discover many typos

Reference article:

Technical blog writing guide - material, layout and picture (jiekun.dev)

Guidelines for Writing Technical Articles - KubeSphere Developer Community

The technical blog writing guide used by all the great gods, made public for the first time, it is recommended to put it next to the pillow- Nuggets (juejin.cn)

How to write a blog post title? - Zhihu (zhihu.com)

How to write a good technical article - Wakakawa

message

If you are always waiting for a good theme, a good inspiration, you may not be able to write an article in your life
Don't be utilitarian, write less XXX interview guidelines, and write more real cases and insights
maintain your own style, maintain your own personality
think about the moment, think about everything

Some pictures in this article are from Wikipedia