English

Technical writing helps a reader do something: use an interface, assess a proposal, reproduce a result, or understand a failure. Begin with that task and the reader’s existing knowledge. A document succeeds when the reader can make the intended decision or carry out the intended operation with the information provided.

Writing also tests the author’s understanding. Explaining a design may reveal an undefined term, an unsupported assumption, or a failure path nobody has considered. This is a practical reason to write during design and investigation, while changing the explanation is still part of changing the work.

Prerequisites and connections: Knowledge of the subject you are explaining and basic writing practice. Reading technical literature (§8.7) supplies examples of how claims and evidence are presented.

The Shape of the Skill: Writing for the Reader, to Think Clearly

Readers need different structures for different tasks. A proposal often benefits from the problem and recommendation appearing early, followed by the reasoning. A procedure needs prerequisites and steps in executable order. A reference needs stable names and a predictable organization for lookup. Choose the structure that reduces the reader’s search and inference.

Clarity requires preserving distinctions. Separate a measured result from an estimate, a current limitation from a planned feature, and a requirement from a preference. A short sentence that drops a necessary condition can be less clear than a longer one that states it.

Imagine a reader who understands programming but has not attended your team’s discussions. Define the local concepts and explain the consequence of each detail that matters. This is more useful than either reproducing all project history or assuming that internal abbreviations explain themselves.

Clarity, Structure, and the Genres of Technical Writing

The Principles of Clear Technical Writing

Use concrete subjects and verbs so that the reader knows who or what performs an action. Replace vague claims with the condition and observable result. Instead of “The optimization substantially improves performance,” write “On the stated dataset and machine, median query latency fell from 100 ms to 80 ms.” Include the measurement method where the decision requires it, and avoid implying that a local result holds everywhere.

Use one term consistently for one concept, and define abbreviations when first needed. State units, ranges, and inclusive or exclusive boundaries. In bilingual documentation, preserve the same distinction in both languages; translating two different technical terms into one word can erase a requirement.

Examples should expose the rule they teach. A normal API call can show basic use; a missing value or failed operation can show the contract’s boundary. Keep examples consistent with the documented version and check that commands and expected outputs agree.

Revise for the reader’s task. Remove repetition and ceremonial introductions, but retain assumptions, causal steps, and limitations that affect use. Read the document without relying on surrounding conversation, then ask a representative reader where they had to guess. Their uncertainty gives you a concrete revision target.

The Design Document

A design document makes a proposed decision reviewable before all of its consequences are expensive to change. State the problem, constraints, and observable success criteria. Then explain the proposed behavior and the assumptions it depends on. Scale the document to the decision: a small local change does not need the same treatment as a new storage system.

Compare meaningful alternatives, including keeping the current design when appropriate. Explain the tradeoff under this task’s constraints rather than describing the selected option as universally better. A prototype or measurement may be needed to resolve uncertainty; record what it establishes and what remains open.

Include the main data flow, failure behavior, compatibility, migration, and verification when they affect the choice. For example, adding a field to a stored record raises questions about old readers, missing values, and rollback. A diagram of the intended steady state is not enough to answer how the existing system reaches it.

Write early enough to expose disagreements, and revise after experiments and implementation change the facts. Preserve consequential decisions and their reasons so that later readers can tell what was chosen and under which assumptions. A design document is useful because it supports a decision and its later review, not because it was completed before any code was written.

The Smaller Genres: Commits, Pull Requests, Incidents, and Documentation

A commit message records a coherent change and the reason a future reader may need. A pull request explains the problem, resulting behavior, implementation choices that require review, and relevant validation. Avoid reproducing a file-by-file diff in prose when the reviewer can already inspect it; supply the context the diff cannot show.

An incident report distinguishes the observed timeline, the evidence-supported explanation, and follow-up actions. State what is uncertain and how an action addresses a contributing condition. Blame directed at an individual usually supplies less technical explanation than describing which information, interface, or check failed to prevent the outcome.

User documentation should let someone complete a task from their starting point. State necessary prerequisites, show the operation and expected result, and explain recovery from likely errors. Interface reference material should define parameters, units, defaults, effects, and failure behavior. Keep examples and instructions tied to the version they describe.

Short documents still need sufficient context. An issue that says only “It doesn’t work” leaves the reader to reconstruct the program, input, expectation, and observation. A concise report can provide all four without narrating every failed attempt.

AI Writing Assistance: Drafting Versus Thinking

AI can propose an outline, identify an undefined term, suggest counterarguments, or revise a paragraph. These uses can support thinking when you evaluate the suggestions against the actual problem and reader. Supplying the decision and evidence first reduces the chance that a fluent draft fills gaps with invented reasons.

Check every factual addition, number, quotation, and claim about what was tested or decided. A polished draft can make uncertainty disappear by changing “may” to “will” or omitting a condition. Compare the revised meaning with the intended one, not just its tone.

Use assistance to reduce the effort of producing a document you understand and can defend. Keep the final text concrete enough that a reader can connect its claims to code, measurements, or explicit assumptions.

What Changes With Mastery

You can choose a structure that fits the reader’s task and revise a claim until its meaning and support are clear. You can also notice when apparent concision has removed information the reader needs.

Test a document by asking another person to use it without extra explanation. Can they run the example, identify the decision, or describe the failure mechanism? Revise where they needed help. This gives more useful feedback than asking only whether the prose sounded professional.

Resources

Books and Texts

Zinsser discusses clear nonfiction; Pinker examines explanations that assume too much reader knowledge; Williams analyzes sentence-level clarity. Strunk and White provide concise English style advice, but individual prescriptions should be evaluated in context. Use these books to revise actual documents and seek feedback from the intended readers.

Book	Role	Type
Zinsser, On Writing Well (30th Anniversary)	Clear nonfiction writing; the foundation	Entry
Pinker, The Sense of Style	Why good writing works; the curse of knowledge	Depth
Strunk & White, The Elements of Style (4th ed.)	Mechanics of clear prose	Reference
Williams, Style: Lessons in Clarity and Grace	Sentence-level clarity at depth	Depth

Courses and Practice Projects

Google’s Technical Writing One provides exercises in words, sentences, and document structure. Diátaxis distinguishes tutorials, how-to guides, reference, and explanation. Write the Docs and Microsoft’s style guide offer further guidance. Practice on a document someone needs, such as a design decision or installation procedure, and revise it after observing where that reader needs help.

Resource	Platform	Type
Google Technical Writing courses (free)	developers.google.com/tech-writing	Practice
Diataxis documentation framework (free)	diataxis.fr	Reference
Write the Docs guide (free)	writethedocs.org	Auxiliary
Microsoft Writing Style Guide (free)	learn.microsoft.com	Reference
Writing in public (blog, docs, forums)	Various	Practice
Design documents during design and implementation	Local practice	Practice
Revising drafts for concision and clarity	Local practice	Practice

Traps

Trap	Why it misleads	Better response
Writing before identifying the reader’s task	The document can be accurate yet unusable.	State what the reader should decide or do.
Removing conditions to sound concise	The shortened claim may become false or ambiguous.	Cut repetition while preserving assumptions and limits.
Listing implementation without explaining the decision	The reader cannot judge why the change is appropriate.	Connect choices to the problem and alternatives.
Treating the initial design document as final	Experiments and implementation can change its assumptions.	Update the decision and evidence as facts change.
Accepting fluent generated claims without checking	Polish can hide invented facts or lost uncertainty.	Verify meaning, evidence, and what was actually done.

中文

技术写作帮助读者完成事情：使用接口、评估方案、复现结果或理解故障。先明确任务和读者已有知识。当读者能根据提供的信息作出所需判断或完成操作，文档才发挥了作用。

写作也检验作者的理解。解释设计时，可能发现未定义的术语、没有依据的假设，或无人考虑过的失败路径。因此，在设计和调查过程中写作很有价值：此时修改解释，本身就是改进工作的一部分。

前置知识与联系：对所解释主题的了解，以及基本写作练习。阅读技术文献（§8.7）提供了表达结论与证据的例子。

这项能力的形状：为读者写作，并借此清楚思考

不同任务需要不同结构。方案通常适合先说明问题和建议，再给出理由；操作流程需要先列前提，再按能够执行的顺序描述步骤；参考文档需要稳定名称和便于查找的组织方式。应选择能减少读者搜索与推断的结构。

清楚表达需要保留区别：测量结果与估计、当前限制与计划功能、要求与偏好，都应分开。删掉必要条件的短句，可能比保留条件的长句更难理解。

设想读者懂编程，但没有参加过团队讨论。定义项目中的局部概念，并解释重要细节会产生什么影响。这比复述全部项目历史，或假定内部缩写不言自明，都更有用。

清晰性、结构与技术写作文类

清楚技术写作的原则

使用具体的主语和动词，让读者知道谁或什么执行动作。用条件与可观察结果代替含糊评价。不要只写“该优化显著提升性能”，可以写“在所述数据集与机器上，查询延迟中位数从 100 毫秒降至 80 毫秒”。当决定需要时，补充测量方法；不要暗示局部结果处处成立。

同一概念使用同一术语，缩写在首次需要时定义。说明单位、取值范围，以及边界是否包含在内。双语文档应在两种语言中保留相同区别；把两个不同技术术语译成同一个词，可能消除一项要求。

例子应揭示它要教授的规则。普通 API 调用可以展示基本用法；缺失值或操作失败，可以说明约定的边界。例子应与文档版本一致，命令与预期输出也应相符。

围绕读者任务修订。删除重复与空泛开场，但保留影响使用的假设、因果步骤和限制。在不依赖周围对话的情况下重读文档，再请目标读者指出哪些地方需要猜测。这些不确定之处，就是具体的修改目标。

设计文档

设计文档让方案在修改成本变高之前能够被审查。说明问题、约束和可观察的成功标准，再解释建议行为及其依赖的假设。篇幅应与决定相称：局部小修改，不需要与新存储系统同样详细的论述。

比较有意义的替代方案，适当时也包括维持现状。根据当前任务约束解释取舍，不要把所选方案说成普遍更好。可能需要原型或测量来消除不确定性；应记录它们证明了什么，还有什么未解决。

当主要数据流、失败行为、兼容性、迁移和验证影响选择时，把它们写出来。例如，给存储记录新增字段，需要考虑旧读取程序、缺失值和回滚。只有目标稳定状态的示意图，无法解释现有系统怎样到达那里。

尽早写作以暴露分歧；实验和实现改变事实后，也应修订。保留重要决定及理由，让后来的读者知道选择了什么、依赖哪些假设。设计文档的价值，在于支持决定及后续复查，而不在于是否赶在所有代码之前写完。

较小文类：提交、Pull Request、事故与文档

提交说明记录一次连贯修改，以及未来读者可能需要的原因。拉取请求说明问题、修改后的行为、需要审查的实现选择和相关验证。如果审查者已经能查看差异，就不必用文字逐文件重述；应补充差异无法展示的背景。

事故报告区分观察到的时间线、证据支持的解释和后续行动。说明不确定之处，以及行动针对哪个促成条件。把责任归结为某个人，通常不如解释哪些信息、接口或检查未能阻止结果，更有技术价值。

用户文档应帮助读者从自己的起点完成任务。说明必要前提，展示操作和预期结果，并解释常见错误的恢复办法。接口参考应定义参数、单位、默认值、影响和失败行为。例子与说明应对应它们描述的版本。

短文档也需要足够背景。只写“不能用”的问题报告，会让读者重新拼凑程序、输入、预期与观察。简短报告可以提供这四项，而不必叙述每次失败尝试。

AI 写作辅助：起草与思考

AI 可以建议提纲、指出未定义术语、提出反对理由，或修订段落。只要根据实际问题与读者评价建议，这些用途可以支持思考。先提供决定与证据，能够减少流畅初稿用虚构理由填补空缺的机会。

检查新增事实、数字、引文，以及关于已经测试或决定了什么的说法。润色可能把“可能”改成“将会”，或删除条件，从而让不确定性消失。应比较修改后的含义是否符合原意，而不只是语气是否顺畅。

让辅助工具降低产出成本，同时确保自己理解并能解释文档。最终文字应足够具体，让读者能够把结论与代码、测量或明确假设联系起来。

熟练之后会发生什么变化

你能够选择适合读者任务的结构，并持续修订结论，直到含义与依据都清楚；也能发现看似精练的文字何时删掉了读者必需的信息。

请另一个人在没有额外解释的情况下使用文档，检验写作效果：能否运行例子、识别决定，或描述失败机制？针对需要帮助的地方修订。这比只询问文字听起来是否专业，更能提供有用反馈。

资源

书籍与文本

Zinsser 讨论清楚的非虚构写作；Pinker 检查过度假定读者知识的问题；Williams 分析句子层面的清晰性。Strunk 与 White 提供简洁的英语风格建议，但具体规则仍需结合上下文判断。应借助这些书修改真实文档，并向目标读者寻求反馈。

书籍	作用	类型
Zinsser，On Writing Well（30 周年纪念版）	清楚非虚构写作；基础	入门
Pinker，The Sense of Style	好写作为什么有效；知识诅咒	深入
Strunk & White，The Elements of Style（第 4 版）	清楚散文的机制	参考
Williams，Style: Lessons in Clarity and Grace	句子层面清晰性的深入处理	深入

课程与实践项目

Google 的 Technical Writing One提供词语、句子与文档结构练习。Diátaxis区分教程、操作指南、参考和解释。Write the Docs 与微软风格指南提供补充指导。选择有人实际需要的文档练习，例如设计决定或安装流程；观察读者在哪里需要帮助，再进行修订。

资源	平台	类型
Google Technical Writing courses（免费）	developers.google.com/tech-writing	实践
Diataxis documentation framework（免费）	diataxis.fr	参考
Write the Docs guide（免费）	writethedocs.org	辅助
Microsoft Writing Style Guide（免费）	learn.microsoft.com	参考
公开写作（博客、文档、论坛）	多种平台	实践
在设计与实现过程中编写设计文档	本地实践	实践
为简洁和清晰修改草稿	本地实践	实践

陷阱

误区	为什么会误导	更好的做法
没有明确读者任务就动笔	文档可能准确却不好用。	说明读者需要决定或完成什么。
为了简短而删除条件	缩短后的结论可能错误或含糊。	删掉重复，保留假设与限制。
只罗列实现，不解释决定	读者无法判断修改为何合适。	把选择与问题、替代方案联系起来。
把初版设计文档当作定稿	实验和实现可能改变假设。	事实变化后更新决定与证据。
未核查就接受流畅的生成结论	润色可能隐藏虚构事实或丢失的不确定性。	检查含义、证据和实际完成的工作。