Technical Writing Guidelines: 10 Essential Principles for Clear Documentation

Experienced engineers often find it difficult to translate code knowledge into clear documentation; the main obstacles are a fixed coding mindset and limited writing skills.

1. Clarify Subject‑Verb‑Object – Ensure each sentence has a clear subject, verb, and (optional) object; restructure ambiguous sentences using conjunctions like "because…so…".

2. Avoid Overusing Pronouns and Transition Words – Use specific nouns instead of vague pronouns; limit transition words to improve readability. Example table of common pronouns and transition words with proper usage:

Index

Type

Name

Example

1

Pronoun

其

In C language,

its

purpose is to improve memory access speed.

2

Pronoun

后者

C++ was invented in the 1980s;

the latter

introduced object‑oriented concepts.

5

Transition

因为/所以

Because

neural networks can automatically extract features,

therefore

traditional feature engineering is unnecessary.

3. Use Strong Verbs and Active Voice – Replace weak verbs (e.g., "run", "appear") with stronger alternatives (e.g., "crash", "throw") and prefer active constructions. Sample comparison table:

Index

Weak Verb

Strong Verb

1

走过去

跳过去

3

出现异常

抛出异常

4. Use Correct Terminology – Keep standard industry terms unchanged (e.g., SDK, TCP/IP) and define custom terms once, preferably in parentheses after the first occurrence.

5. Use Appropriate Paragraphs – Each paragraph should convey a single idea; start with a clear opening sentence that summarizes the paragraph’s topic.

6. Control Paragraph Length – Avoid overly long paragraphs; aim for 5‑7 sentences and keep them concise.

7. Use Lists and Tables Effectively – Convert dense text into ordered or unordered lists when enumerating steps or points; ensure list items share the same structure (all nouns, phrases, or sentences). Example of a corrected list for a daily work log is provided.

8. Use Tables for Structured Data – Organize numeric or structured information in tables; include clear titles and maintain consistent styling. Example tables compare programming languages and list punctuation rules.

9. Maintain Consistent Style – Follow a document style guide for fonts, margins, spacing, and headings; ensure uniform formatting across the entire document.

10. Keep Overall Document Structure – Plan a high‑level outline before writing; for complex documents, draft the outline on paper and refine it iteratively. Provide a sample outline for a technical feedback report, showing sections such as background, existing logic, challenges, and solution proposals.

Throughout the article, visual aids such as diagrams and screenshots are recommended to complement text, with clear captions and highlighted focal points to improve comprehension.