For programmers, writing technical articles is very important, whether it is to summarize reports in the company, or to increase the influence of the community, writing ability is indispensable.

I have summarized my experience of writing technical articles before, called “What is the core of technical articles? Talk about my thinking”, mainly talking about the core of technical articles is logical clarity.

It’s been a while since that article, and I’ve stepped on a few more potholes with some new insights:

On the basis of clear logic, technical articles should further pursue the readability and practicality of articles, improve the reading experience (that is, the feeling of enjoyment when reading), and enhance the appeal and value of articles.

To improve the reading of technical articles, we should consider the following points:

interlocking

If doing logical and clear is the foundation of technical writing, it is the progress of technical writing.

Loop means that you don’t want to talk all at once, you want to leave an information gap that leads to the next part of the text, and then close the loop at the end of the text.

From the beginning of the title to leave a gap of information, arouse curiosity, attract readers to continue to read, so that the completion rate will be relatively high. Finish read rate is high, other data will be good.

Here’s a bad example:

This article is about how Nest. Js performs parameter verification, and introduces the functions of Pipe and ExceptionFilter through this case.

In fact, the content is ok, there are introductions of these two mechanisms and cases of running, but the data is not very good compared with other articles.

Then I thought about the reasons and found two problems:

  • The title is closed directly, leaving no information gap:

It directly lists all the content in the title. Although it is a summary of the content of the article, there is no information gap, which will make people not want to click. How to Validate Parameters in Nest.js would have been better.

  • The first paragraph also lists the technologies that will be used.

In fact, there is no need to list the points to be covered, because the reader will not know what it is, but because they know what will be covered, they will lose some expectation of what will be covered.

This should lead to the topic of “back-end parameter validation”, pique the reader’s curiosity, and then explain little by little how Nest.js does parameter validation. Close the loop at the end of the article and make a complete summary.

Technical articles that can be linked together are more attractive because the process of reading satisfies the reader’s curiosity and makes the experience more enjoyable.

interactive

Reading technical articles is actually a two-way communication between the reader and the author. The author says something that will arouse the reader’s thoughts or emotions, and then the reader will continue to read based on these thoughts or emotions.

If you throw a question in the right place, or put a meme in the right place or something, there’s a lighter interaction and a better reading experience.

However, interaction is not too much, appropriate ornament can, can tell the content clearly from the logic is the most important.

Paring down

The simpler the content, the better, on the basis of ensuring the integrity of the content.

The more succinct and clear your message, the easier it is for the reader to read and the better the experience. No one likes a long story that misses the point.

highlight

An essay must have something you want to say. Make it bold and highlight it.

The author must be more clear about what the point of the article is, directly marked out, do not need to let the reader to think about the summary, so it will be easier to read. And readers who like speed reading can also quickly get the content that the article wants to express and meet the needs of this part of readers.

practical

Learn the technology to use, so the technical article case should be as practical as possible, and preferably provide complete runnable code.

Many of my previous posts have provided runable cases and posted the code to Github or posted it in its entirety. So the reader, after he or she has thought it through, can just run the code down and give it a try.

This is how I write my little books and articles:

Reading through the article is not the ultimate goal, can be further used, so that the value of the article will be greater.

The headline should inspire curiosity

I’m not very good at making headlines, so MY reading goes up and down:

This aspect I also in the study 😭.

I was reading some new media writing recently, and I mentioned one point:

From the title to stimulate the reader’s curiosity, it is best to physiological want to read, is not thinking, subconscious want to see.

Of course, this doesn’t mean clickbait. It just means changing the way you start a headline, refining some of the points that readers will be interested in and putting them into the headline to make the article more appealing.

In fact, one of my most read articles last year might have been entitled:

It not only points out what the article is about, but also stimulates the reader’s curiosity.

conclusion

Technical articles should be logical and clear first, which is the most basic, but to be brilliant, there is more to be done:

  • Link: Each section should leave an information gap to keep the reader reading, and then close the loop at the end of the article. Improving the read rate is the basis for other data.
  • Simplify: On the basis of complete expression content, the more concise the language is the better, so that the article will be easier to read.
  • Practicability: Learning techniques for the purpose of use, the case of the article should be as practical as possible, and to provide complete runnable code.
  • Highlight: Highlight what you want to highlight so that the reader can easily get to the heart of the article.
  • Interactivity: when readers read an article, it is a two-way communication with the author. Appropriately increasing some emotional or thinking interaction will increase readers’ reading experience.
  • The headline should inspire curiosity: The headline should make the reader want to read it physically, so extract the most interesting and valuable points from the article as the headline. The title is the beginning of the article and the importance is very high.

These are my conclusions after writing a large number of technical articles: Technical articles should constantly pursue readability and practicality on the basis of clear logic, so as to increase the appeal of the articles and readers’ reading experience, make the articles more enjoyable to read and convey more value.