How Architects Can Master Technical Documentation

Why Writing Technical Docs Is Hard

Experienced engineers often find it difficult to describe problems or solutions in writing because most of their thinking is code‑centric, and their prose skills are uneven, much like a programmer who writes flawless code but struggles to express ideas in sentences.

Two Core Reasons

Fixed mindset: heavy focus on coding leaves little practice in textual expression.

Limited writing ability: just as code quality varies, so does prose quality.

Both can be improved through regular practice such as blogging, but systematic study of “technical writing” theory yields faster results.

Ten Practical Guidelines

Master Subject‑Verb‑Object – Every sentence should have a clear subject, verb, and (optional) object. Example of a faulty sentence and its corrected version are provided.

Avoid Overusing Pronouns and Transition Words – Use concrete nouns instead of ambiguous pronouns. Sample tables of common pronouns (e.g., “其”, “后者”) and transition words (e.g., “因为/所以”) show proper replacements.

Use Strong Verbs and Active Voice – Replace weak verbs like “走过去” with “跳过去”. A list of weak vs. strong verb pairs (e.g., “切肉” → “砍肉”) illustrates the point. Active sentences are shorter and easier to read than passive ones.

Minimize Adjectives and Adverbs – Replace vague modifiers with concrete numbers. The article rewrites a paragraph about image compression, turning “尽可能压缩图片尺寸，事实证明非常成功” into a precise statement with measurable improvement.

Use Correct Terminology – Keep standard industry terms (e.g., SDK, TCP/IP) unchanged and define custom terms once, using short parenthetical explanations or a dedicated glossary.

Structure Paragraphs Properly – Apply the “single‑responsibility” principle: each paragraph should convey one idea, start with a clear opening sentence, and stay within 5‑7 sentences.

Craft Good Opening Sentences – The opening line should hint at the paragraph’s topic, helping readers decide whether to continue.

Control Paragraph Length – Keep paragraphs concise; split overly long paragraphs into shorter ones or merge very short ones when appropriate.

Let One Image Speak a Thousand Words – Use diagrams or screenshots to convey concepts quickly. The article shows a double‑linked‑list illustration and explains how adding a relevant image dramatically improves comprehension.

Use Lists and Tables Wisely – Convert dense text into ordered or unordered lists, ensuring each list item shares the same structure (all nouns, phrases, or sentences). Examples demonstrate turning a narrative about a developer’s daily tasks into clear bullet points and numbered steps.

Examples of Common Mistakes and Corrections

Incorrect pronoun usage: “它” ambiguous – corrected to repeat the explicit noun.

Passive sentence: “角色权限是由管理员控制的” – revised to active “管理员控制角色权限”.

Overly long paragraph about C++ history – split into three concise sentences, each ending with a period.

Visual Aids

Images are inserted to illustrate concepts; each image includes a concise caption.

Overall Document Structure

Before writing, outline the document hierarchy (titles, sections, subsections). Identify the target audience early; the article stresses that knowing who will read the doc influences tone, depth, and terminology.

Finally, the author provides a checklist summarizing the key practices: use strong verbs, limit adjectives, keep paragraphs focused, start with a clear opening, leverage lists/tables, and supplement text with well‑captioned images.