As for me, I don’t write many satisfying articles in a year. Because writing a good technical article is really hard.

For a good essay, it has these requirements:

  • Construct the theoretical system needed for the article
  • Practice and code validation
  • A fair and partial view

Here are a few things to note:

  • Refute false claims, but don’t limit yourself to arguments
  • Pursue the value of the article to yourself and the reader
  • Typography and syntax highlighting
  • Watch out for typos and technical words

Note: the technical article referred to here is not a relevant answer to a question. Instead, they focus on a few knowledge points, structures, etc., complex articles.

Construct the theoretical system needed for the article

Blog, light just use knowledge points every day, then a week down, even can record a book. Writing an article is not as easy as writing code. You need to clarify your thoughts — why you were thinking A, then B, or how to find C. If the Debug process is written down, the reader may learn some ideas from it. A book, on the other hand, is a collection of related articles, plus code practices, so that readers can have a deeper understanding. It can take months or even years to write a book.

It is even more difficult to organize production code knowledge. For example, when I wrote my ebook Serverless Architecture Application Development Guide, I bought almost every Chinese book I could get my hands on, as well as Packt e-books. Although it is only a reng tube on GitHub ebook, as my work, it represents me to some extent.

Before you write an article, you always have to clear your mind. Technical articles, in the final analysis, are still in learning, good technical articles are bound to come out of practice. Unlike ordinary gossip articles, technical articles must be based on data and practice, rather than hearsay or Copy/Paste From Google.

But it’s not easy to do, for example, I spent about a month designing such a recommendation system when I wrote a three-step article about how I designed a recommendation system for tech blogs. In order to verify the wording and algorithm accuracy of the article, I read a series of articles and books, and wrote two or three algorithm demos. Finally, I finally confirmed the general idea of the article.

Practice and code validation

Once we have a clear theme and idea, we need to prove it works. It’s like consulting projects where the client has an idea in mind but needs you to implement it. For example, when I was imagining an edit-develop-publish architecture, IT took me almost half a month to build a DEMO application using GitHub + Travis CI.

The general code verification is pretty easy. Some validation, however, is sentimental. For example, to test whether Windows, macOS or Linux is better, we need to find all three operating systems and use them for a month. Will I know if I’m right about Windows for gaming and engineering, macOS devices for design and programming, Linux as a server?

Conclusion has, then the evidence also must have. That’s when we need to prove that there aren’t many games on the Mac, and there’s a lack of professional engineering software. Then had to put the relevant software one by one listed, a comparison. Well, that’s the conclusion, or maybe that’s not the conclusion.

If you’re wrong, the comments section will be abuzz. For the sake of the comment section, there will always be people who throw out the erroneous conclusion that “PHP is the best language in the world”.

A fair and partial view

No article can satisfy all people. Try to write an article that pleases everyone, looks like nothing, and then pleases everyone.

Therefore, an article should focus on expressing the author’s own opinion, which should be based on the theory of why Angular is better for large front-end applications, rather than repeating that Angular is better for large front-end applications. If you don’t want to offend people who like a framework, you need to be subtle. For example, I have no experience developing large applications with XXX, or it lacks the requirements of XX.

Refute false claims, but don’t limit yourself to arguments

Debating whether PHP is the best language is meaningless in and of itself. We just want to convince each other, and convince each other, to prove that we are. The argument was never that PHP was the best language, but that I was right.

The mark of an education is that you can accept an idea without accepting it.

It is not easy to accommodate the views of others. Most of the time, it may be that we can’t put ourselves in each other’s shoes because we can’t imagine what the other person is going through. For example, poverty limits our imagination.

“On the Internet, no one knows you’re a dog.”

Of course, “If criticism is not free, praise is meaningless.” As a writer,

It’s easy to be a keyboard warrior. You just need to connect to the Internet. Most debates are meaningless, and it’s hard to understand the context of something, so most people don’t bother. Even if you repeat it in your article. Later, even if the other person understands later, it is difficult for him or her to admit that he or she was wrong. The worse things get, the harder it is to get out of control.

In an argument, both sides feel that they are right and the other is wrong. As long as one side thinks, “Gee, that makes sense, but we should try,” then the argument is over.

Whether one should make proper concessions is another matter.

Typography and syntax highlighting

Good typography, syntax highlighting style, these two elements can be put on our professional coat. For me, keeping the design consistent and customizing the style of the front end display.

Although they do not affect the quality of the article:

  • Good typography provides a good reading experience
  • Code syntax is highlighted to make you look more professional.

Typesetting, it is a kind of detailed activity, it is not easy to do well. For most techies (including me), this is a natural lack of beauty. In addition, general technical writing is managed by Markdown + Git first, and then specific editing tools, such as Word and wechat editor, are used. At last, platform inconsistency is easy to occur in experience. I use my own tools and themes to unify typography across different platforms.

Figure captions. Technical articles, like long articles, have one problem that is not easy to read. One way to improve the user’s reading experience is to insert related illustrations between paragraphs, perhaps to create a visual transition. Concerned about copyright, I started to make my own drawings.

The code syntax is highlighted, and the technical articles have visited campus (ES) with code to experience the truth. Therefore, code is the test of theory and architecture. Interweave code in your text to be reader-friendly, and a common way to be reader-friendly is by highlighting code syntax. This is why I wrote my own wechat official account editor last year. There is no markdown editor in the market that supports the syntax highlighting of wechat official account.

Watch out for typos and technical words

High quality articles, for me, there has always been a typo problem in my articles. However, without affecting the reading of the article itself, it may not affect the quality of the article. But when it matters, it often affects the quality of the article.

I used to think I had time to correct the typos, but I didn’t. But what is said to be changed in the future will basically remain unchanged in the future. Because we think it’s tolerable, it’s not as high a priority. We only find things when we are better than nothing.

My ebook experiences at GitHub have taught me that readers are often the ones who find typos more easily. I’m almost used to it. It’s not easy to tell how to use the word “join”, for example. For the most part, I use joins.

Java 8, Java or J8, I think we all know the answer to that question. As an engineer, you have to make sure your words are accurate. For example, Java 8 refers to the 8th generation of Java language, Java refers to the command line tool of Java language, J8 is used to curse people. The same is true for other languages and architectures, such as Python and Ruby. Python is a command line tool that allows access to the Python command line.

Reading or self-worth?

The pursuit of reading volume is a terrible thing for tech blogs and public accounts. In the same pursuit, future writers may turn technical articles into technical gossip, because only hot topics and gossip are welcomed by people. For traffic and profits, chasing hot topics is nothing more than collating other people’s opinions into articles and seeing the responses in readers’ comments. For a long time, I am afraid I will not write a thoughtful article.

In other words, thoughtful writing does not mean that the writing is thoughtful, but that it prompts the reader to think. Inevitably, most people have become accustomed to not thinking, and thus reading less.

Most of the time, we don’t care what’s going on, north, south, east, west, because it’s so far away from us. People usually only care about things that are relevant to themselves and their surroundings, or gossip and trivia that can be used for conversation.

In the past, I also pursued the amount of articles I read. It was only by chance that I came into contact with Content Strategy that I realized I needed high-quality articles. Highly read articles are generally time-sensitive. This article may not be of any use for weeks or months. High-quality articles, however, tend not to have this problem.

When I began to understand the importance of quality, something changed in my thinking. I began to document some of the changes as I grew up, and the reading was far from ideal. But every time I read these articles, I come up with new ideas. Most of these articles are written by your future self. I stopped trying to read more and started to improve the quality of my articles.

As a result, I became a clicker when it came to balancing the quantity and quality of reading. A good title can often improve the opening rate of the article.

conclusion

Well, pay more attention to my official wechat account (Phodal-Weixin) for more timely and useful technical knowledge.