Teach you how to write technical articles

preface

It goes without saying that coding skills are important to software engineers, but technical writing skills are also important. A good design document can guide the development and testing of requirements, improve the quality of software; A good user document can help users quickly familiar with the use of software; A good technical blog post can be refreshing and rewarding; A good summary of experience can help beginners avoid detours.

The goal of technical writing is to enable the reader to use a piece of software or understand a technology or understand a business process. The biggest difference between technical writing and creative writing is that technical writing does not seek to please the reader, but to clarify facts in concise and precise words.

A good technical article should enable qualified readers to understand and even master the content of the article under a good reading experience.

Technical writing is a knowledge, many students more or less have the idea of writing some technical articles, but because of the lack of some basic writing skills, often have no way to start. This article will give some technical writing advice, and strive to make software engineers can write technical articles, love technical writing.

Why technical writing

As mentioned in the preface, a good technical article can bring many benefits to readers. In fact, technical writing can also bring great benefits to the author himself.

Improve your presentation skills

How to organize articles, how to express complex technical principles in a comprehensible way, this is a great test of one’s ability to express.

Strengthen structure and logical thinking

Articles, like software, have architecture and logic. One important reason why PHDS are generally strong in structure and logical thinking is that they have been honed by rigorous dissertation writing. When we write well, architecture and logical thinking are enhanced, and software design and development capabilities are enhanced.

Deepen technical/business understanding

Writing technical articles well requires familiarity with what you are writing about, which naturally requires the author to do his or her homework before writing, which in turn leads to a deeper understanding of the relevant technology/business.

To show themselves

Sharing your knowledge through technical articles is a great way to show off what you’re currently familiar with and expand your influence over time, which can be a great help in your career.

heart

Publishing a technical article on an open platform, getting a lot of page views, comments, likes and favorites from readers, can be a spiritual pleasure.

How do YOU start technical writing

All things are difficult at the beginning. For software engineers who are used to dealing with code, it is difficult to start technical writing with words. I believe that many students have encountered the dilemma of holding back for hours without writing a few words, or struggling with what to write. It’s not that hard to get started on technical writing if you just find some way.

Start by recording your studies/work

You can start by recording your daily study/work content and gradually get used to working with words. This process focuses on building confidence in writing.

The length of the article is not important

Don’t set out to be the best tech blogger you can be. It’s not just long writing that makes a good technical essay. Some short notes on problem solving and experience summary can also be of great help to readers.

Find inspiration for writing through study

If you’re struggling to figure out what to write, learn a new skill or read a book. The best time to write is when you’re just learning something, because that’s when you know exactly how to go from zero to one, and that’s what you want to convey to the reader.

Learn to take notes

Notes are very good writing materials, in the daily work and study to make more notes, to record their own inspiration, writing up will be easier.

Trilogy of writing

Step 1: Set a writing goal

The first step in writing is to set a goal, define what kind of article you want to write, and write towards that goal. For example, if you set the goal of introducing the HashMap data type in Java, don’t write an article describing how garbage collection works for the JVM, which confuses the writing goal.

Step 2: Identify your audience

The second step in writing is to identify an audience and write only what that audience can accept. For example, if you want to write an article entitled “Learning the Java language from Scratch”, which is clearly aimed at Java beginners, do not analyze the JVM memory management implementation source code in the article, which will confuse the article audience.

Step 3: Organize your essay

To organize an article is to connect the knowledge to be expressed into a coherent article according to the central will. Many newbies face the dilemma of having so many ideas but no way to write. This is due to the lack of organization. As mentioned in The book Wen Xin:

For the organization of the article, also may wish to cite a general method, that is, ‘ask yourself’ four big words.

We can organize our articles by asking ourselves questions, such as “How to Write good code comments” :

“Are you writing this article to say something?”

To summarize some ways to write good code comments. In this way, the main idea of the article is clear.

“Where does the central content come from in our minds?”

— I was deeply impressed by the chapter about code comments in A Philosophy of Software Design and would like to share it with you. In this way, the scope of the material the article is based on is confirmed.

“Does this material increase the power of the central message?”

The book’s examples of high-level and low-level annotations are a good example of what makes a good code comment. In this way, we can continuously screen out good material and confirm the main content of the article.

“Is there a more succinct expression?”

B: It seems to make it easier to write it this way. So after constant revision, an article will come out.

Some technical writing advice

1. Get familiar with the content of the writing

As the author of the article, you need to know the content better than the reader. You may not be an expert in your field, but at least be able to articulate your knowledge and answer most readers’ questions. This requires taking the time to read articles, books, and even experts before writing.

Make an outline before you write

The article is not only to list the content, to pay attention to the expression of knowledge, so it needs a clear article structure. Making an outline before writing will help you clarify your thoughts, make sure your content is logical, and create a clear structure for your essay. Think about it. What needs to be explained first? What is the order of the paragraphs? What needs more explanation? Which points will do?

3 Simplified text

Technical writing is not scripted fiction. It does not need twists and turns, let alone innuendo. It pursues a direct, practical and clear style of expression. There is no need to use overly complicated words to describe technical principles, which only makes them harder to understand. Use concise text and short sentences to make your text more readable.

4 give more examples

Avoid writing an entire technical treatise, which can be too boring and difficult to follow. Use more examples, not only to make the technical principles easier to understand, but also to deepen the theme. For example, in “Teach you to Write good code comments”, by giving examples of positive and negative code comments, readers can better resonate with good code comments.

5 Use charts

Sometimes we encounter things that are difficult or require a lot of words to describe, such as complex business processes and module dependencies. This can be visualized with diagrams. The right diagram can clearly illustrate the technical principles more than a thousand words.

Some drawing software recommended

• Suitable for beginners: MicroSoft Office PowerPoint, MicroSoft Office Visio, Apple Keynote
• Online drawing: draw. IO, ProcessOn, Excalidraw
• Code drawing: PlantUML
• Hand-painted style: Apple Keynote, Excalidraw
• Advanced players: Sketch, Lunacy

6 Code segmentation

In depth analysis of some technical principles or system framework, we often involve source code analysis, do not directly post hundreds of lines of code in the article, and then use a paragraph before/after the code to explain it. This can cause the reader to turn the page up and down frequently in order to match the code to the instructions, which can seriously affect the reading experience.

What not to do:

.inline void* oopDesc::field_base(int offset) const { 
return (void*) & ((char*)this)[offset];
}
template <class T> inline T* oopDesc::obj_field_addr(int offset) const {
return (T*)field_base(offset); 
}
There are hundreds of lines of code left.Copy the code

As you can see from the code snippet above, each field in the OOP has a corresponding offset, XXX.

A better approach is to break the code into sections and intersperse them with key comments.

Positive examples:

// Call obj_field_addr based on offset to check whether pointer compression is used before retrieving field
// Get the address of field, then call load_decode_heap_oop to get the instance
inline oop oopDesc::obj_field(int offset) const {
return UseCompressedOops ?
 load_decode_heap_oop(obj_field_addr<narrowOop>(offset)) :
 load_decode_heap_oop(obj_field_addr<oop>(offset));
}
Copy the code

The oopDesc::obj_field method is primarily used for XXX.

// The base-type specific implementation is similar to obj_field_addr, but transforms into a base-type specific pointer
inline jbyte* oopDesc::byte_field_addr(int offset) const {
return (jbyte*)field_base(offset); 
}
Copy the code

OopDesc ::byte_field_addr Is used for XXX and will be invoked in XXX.

7 Repeated corrections

Good articles are produced after repeated corrections, not only limited to the correction of misspellings and words, but also to review the whole article from the perspective of readers and even reviewers. How can I make this paragraph clearer? What knowledge needs to be extended? Which pieces can be cut out?

Make it a habit to read your articles carefully before you publish them, and avoid silly mistakes. This is the greatest respect for your readers.

8 Do layout

Just as code needs to be segmented, text needs to be segmented, and a large chunk of text can get boring. The key sentences/words need to be bolded and highlighted; Use headings and organized/unordered lists to make your writing clear.

It is recommended to use Markdown for technical writing. Its layout is simple and beautiful, and its syntax is simple. Most platforms support the publication of articles in Markdown format. In addition, you can use typography tools such as Markdown-nice to customize the background, color, font, etc., to improve the reading experience.

9. Read good articles

Develop the habit of reading good articles, learn their writing style, and constantly improve their writing skills.

conclusion

“Wen Xin” summarizes article writing into three stages: practice, application and creation.

Exercise is just the practice of rules and wrists, application is just to deal with other people and things, creation is the real achievement of their talents.

Technical writing is the same. The first stage exercises correspond to summary articles such as reading notes and experience sharing. The second stage of application, corresponding to the work of design documents, user documents and other guide documents; The third stage of creation corresponds to articles like “Views on the Future Development of XXX Field”, which often requires the author to have a deep knowledge reserve.

Of these three, the most basic, the most important is exercise. Only when the exercise to a considerable degree, can have application, also can talk about creation.

There are many ways to write good technical articles, but one of the simplest and most effective is: Don’t stop writing.

reference

• Wen Xin, Xia Mianzun/Ye Shengtao
• How to write technical articles to have a better reading experience, Fan Wu
• Technical Writing: Definition and Observations, Richard Nordquist
• 15 Tips to Improve Your Technical Writing, TBS Staff
• Advice for Technical Writing, Chris Coyier
• Developers: The Why and How to Writing Technical Articles, Goodness Kayode