10 Key Principles for Effective Technical Writing

Experienced engineers often find it difficult to translate code into clear documentation; the main reasons are a fixed thinking pattern from heavy coding and limited writing ability. Systematic practice, such as regular blog summaries, can help, but deliberately studying "technical writing" theory yields greater efficiency.

1. Master Subject‑Verb‑Object

Sentences should contain a clear subject, verb, and (optional) object. A well‑structured sentence reads smoothly, while missing or misplaced elements make the text awkward. Examples demonstrate how to rewrite a poorly formed sentence about traditional image‑processing algorithms into a clear, logical form.

2. Avoid Overusing Pronouns, Transition Words, and Punctuation

Pronouns (you, it, its, etc.) and transition words (because/so, first/then) must refer unambiguously to previously mentioned nouns or clauses. Tables illustrate common pronouns and transition words with proper usage examples.

#

Type

Name

Typical Context

1

Pronoun

其

C language introduced the concept of

pointers

,

its

purpose is to improve memory access speed.

2

Pronoun

后者

C was invented in the 1970s, C++ was invented in the 1980s,

the latter

introduced object‑oriented concepts.

5

Transition

因为/所以

Because

neural networks can automatically extract features,

so

deep‑learning techniques no longer need traditional feature engineering.

6

Transition

首先/然后

First

we must ensure enough training data,

then

we select a suitable neural‑network model.

Overuse leads to ambiguity; the article provides corrected sentences that replace vague pronouns with explicit nouns and adds clear transition words.

3. Use Strong Verbs and Active Sentences

Strong verbs convey actions more directly. A table compares weak verbs (walk, cut, encounter exception) with stronger alternatives (jump, hack, throw). Active voice is preferred because it reduces cognitive load, improves clarity, and shortens sentences.

#

Weak Verb

Strong Verb

1

走过去

跳过去

2

切肉

砍肉

3

出现异常

抛出异常

Active‑voice examples replace passive constructions such as "role permissions are controlled by the administrator" with "the administrator controls role permissions".

4. Minimize Adjectives and Adverbs

Technical documents should be precise; replace vague modifiers with concrete numbers or facts. Examples show how to turn "the system runs more efficiently" into "the system response time improved 2×".

#

Adjective/Adverb

Suggested Revision

1

接口响应速度提升明显

接口响应速度提升2倍

2

现场误报很多

现场误报率为11%

3

系统很不好用

最近一个月有超过50个客户投诉系统不好用

5. Use Correct Terminology

Maintain standard industry terms (SDK, TCP/IP, micro‑service) without altering spelling. For domain‑specific terms, provide a concise definition at first occurrence, preferably in parentheses, and keep the explanation to one occurrence only.

#

Term

Explanation

1

SDK

Software Development Kit – a set of tools for developers to build higher‑level applications.

2

内存泄漏

Memory leak – memory allocated via new/malloc that is not released after use.

3

面向对象

Object‑oriented – encapsulation, reuse, and extensibility of code.

6. Write Single‑Responsibility Paragraphs

Each paragraph should convey one main idea, beginning with a clear topic sentence. Example shows how to split a long Excel description into two focused paragraphs.

7. Control Paragraph Length and Opening Sentences

Keep paragraphs to 5‑7 sentences, start with a concise opening that previews the content. The article demonstrates improving a paragraph about loop statements by adding a clear opening sentence.

8. Use Lists and Tables Appropriately

Convert dense text into ordered or unordered lists when enumerating steps or items. Ensure list items share the same structure (all nouns, phrases, or full sentences). Tables are ideal for numeric data; keep cell content short.

#

Language

Brief Intro

1

C

Compiled, low‑level, fast, high learning curve.

2

C++

Compiled, adds object‑orientation, similar learning curve.

3

Python

Interpreted, simple syntax, popular in AI.

9. Use Images Effectively

Images can convey concepts faster than text. Include a concise caption, highlight key areas, and avoid overly complex diagrams. The article shows how to split a large system architecture diagram into smaller, focused images.

10. Maintain Uniform Style and Overall Structure

Adopt a consistent document style (margins, fonts, spacing) and follow a logical outline: start with background, present analysis, propose solutions, and conclude. Draft an outline before writing, especially for non‑standard reports.

By applying these ten points, technical writers can produce clear, concise, and reader‑friendly documentation.