preface

A friend recently asked me how I could get started on my own writing without ever writing a blog. I thought about this a lot and finally decided to write an article to share my thoughts on how to write a good technical article.

First, clear standards

There are norms for everything you do, including writing articles. First, we need to clarify some considerations:

  • Eliminate undesirable content
  • Avoid sensitive topics
  • Stop copying and copying
  • Cite source

I believe that the original intention of writing is the love of technology and the desire to share knowledge, so the above problems will not occur, so I will not expand on it here. It is recommended that you read the official nuggets handbook: Using Nuggets: standards and Specifications for Nuggets Community Content at 📐.

Second, determine the main idea

2.1 Clear central idea

Before writing the article to clear the central idea of this article, for example, I want to solve a XXX problem, then around this problem to expand, if there are more than one problem or to tell the content, it is necessary to simply refine, summarize in the preface, and divided into multiple chapters and paragraphs.

2.2 Good article titles

After determining the main idea of the article, you can begin to conceive the name of the article. A good name is the best publicity for the article. It is best to reflect the core technology stack or problem-solving ideas of the whole article, after all, the technical article, mainly to solve the problem, read what you can harvest this article, read the title of the article can roughly think of is the best. Here are some random titles that I think are good.

First came the concise title. This kind of title can directly reflect its main content, concise but not simple:

  • Vue’s fun new feature: JS variables in CSS
  • React Hooks + Project Combat
  • Console 3000 Word complete Guide to more than console.log!

Or you could consider this slightly pompous headline:

  • “Code efficiency increases 80% with these 25 regular expressions”
  • “100% Improvement in development efficiency 🔥” From zero to one you quickly implement enterprise-class CLI tools 🐬
  • “Every time start the project service, the computer actually obediently help me open the browser, 100 lines of source code revealed!”

And, of course, you deserve this cute headline:

  • Front-end Ice Cola 🥤 | With 50 lines of code become luozhu 🎋 upgrade lv5 key Mr.
  • Byte not to everyone hair moon cake? 🎑 that I personally hair to everyone! 🥮 everyone has!
  • “Every front-end deserves its own component library, like a watermelon every summer 🍉”

2.3 Brief introduction

A good article usually has a preface/introduction, which is used to introduce the main content of the article, as well as some of the author’s personal views, the process of writing the article and so on. As part of the informal content of the article, the introduction is very important, after all, readers will see the introduction immediately after the cover of the article, so it needs to be polished. Forewords help retain readers rather than drive them away. Good forewords generally have the following characteristics:

  • Concise and clear, strong generalization
  • To draw attention from scripture

Finalizing the framework

3.1 What is a “Framework”

Article frame is the overall structure of the article, after writing the preface, you have to start to conceive the structure of the whole article. At this stage, you need to divide paragraphs according to the content you tell. If the content is more, you can also divide big chapters. However, it is not recommended to make the article too long, the article is too long easy to make readers tired psychology, the article can be split, split into the upper, middle, or serial form.

3.2 How to Divide

In short, you should have the general outline of your essay before you start writing the details, and then fill in the details. Had better divide according to the primary and secondary of the main content of the article. If it is to share code blocks, it will be divided according to its category. The priority of sorting is generally positively correlated with its importance; If it is about solving problems, it should be divided according to the steps, and a chapter should be divided when the solution reaches a certain level, which is also convenient for readers to track the progress. Here is an example of a paragraph by category:

  1. XXX (the more important or attractive)
  2. 2, Classification XXX
  3. And so on…

If it is a problem solving article, it can be divided as follows:

  1. The business scenario
  2. Implementation approach
  3. coding
    1. The first step in the coding process
    2. The second step of the coding process
    3. And so on… (A final summary)
  4. Problems of divergence

3.3 Use headings wisely

It is common for large modules to have level 1 headings, such as preface, references, articles, and large modules. The larger module can then be split into smaller secondary modules, with secondary headings, smaller headings for more subdivided content, and so on. But can not abuse the title, otherwise it appears that the content of the article is empty, a glance is full of titles; Always let content take over (in this case, text and code). It is perfectly possible to write the content after building the level 1 heading, and then break it up into smaller modules if it becomes too long.

Fourth, improve the content

4.1 Refine language and improve reading efficiency

When writing an essay, try to simplify the text (especially modifiers) and avoid multiple sentences that have similar meanings. Just like writing code, abbreviate when you can (like syntax candy), but don’t oversimplify, because it’s too easy for the reader to understand. If you have a concept that needs to be introduced, you can actually break out the detailed section as a small paragraph, and then add a description such as “familiar people can skip.”

4.2 Standardize the code to reduce reading costs

4.2.1 Description of the first line

After reading a lot of good articles, I found that most authors put a comment in the first line of a code block indicating which file it is, such as utils/index.js, ModuleName/index.less. The advantage of doing this is easy for readers to understand and read later.

// utils/index.js specifies which file it is
// Specify the code...
Copy the code

4.2.2 Code Formatting

Be sure to format your code with an editor (such as VScode) before pasting it into your article to avoid typographical errors. (People with obsessive-compulsive code formatting see good)

Beautify and prettier-code formatter are recommended for Vscode.

4.3 Exquisite illustrations to ease reading pressure

When there is too much text in one paragraph of a text, it tends to increase the reader’s reading pressure and make it easier to dissuade the reader (think of long, lengthy documents). In addition to breaking it down into smaller paragraphs as needed, add more illustrations. There are generally the following types of illustrations:

  • Mind mapping series
  • Screenshots (usually code execution results demo)
  • Illustrations/Posters

Mind maps can be made directly by using the editor or software XMind, including other maps, such as flow charts, Gantt charts, etc., which are auxiliary descriptions of text or classification of content outline. The image below is from XMind:

A screenshot here is a screen capture of a function or operation flow described in the article to better show how the code works, or to better demonstrate an operation flow. Of course, sometimes giFs work better. Here are some recommended screenshot tools:

  • Snipaste
  • ScreenToGif
  • LICEcap

Finally, I would like to talk about the cover of the article. If conditions permit, you can make the cover by yourself and make corresponding pictures according to the content of the article. A series of articles can be corresponding with similar article covers. Of course, wallpaper or non – commercial posters are also acceptable.

4.4 Organize typesetting to improve reading experience

As the content of the article gradually fills up, good typesetting becomes more and more important. We can refer to the following methods for optimization:

  • Leave space between images and code blocks
  • When a paragraph is too long, break it up with blank lines
  • useAn ordered list 和 Unordered listInstead of long words

Five, check for errors

Once you have written your article, you need to enter the error checking phase. The main purpose of the error check is to correct some key points, after all, it is embarrassing to have problems in prominent places. Depending on its importance, checking for errors can be roughly divided into several steps:

  1. Check article titles and level 1 titles for typos
  2. Check the preface for typos and wrong sentences
  3. Check that the links in the article open properly

Vi. Review the full text

The last (optional) step before sending a document is to read the full text after checking key positions such as headings and preface in the previous step. This time, put yourself into the identity of the reader, the investigation of the possible existence of unclear meaning, sentence is not smooth problems. Usually, writing an article is to express the author’s ideas in words, which will inevitably be colloquial. In the same way that readable code is more popular in everyday development, writing articles should make it more accessible to readers.