technical-writing

技术文档写作

摘要：写好技术型文档是工程师进阶的关键技能。核心原则包括：搞清楚主谓宾、不滥用代词、多用强势动词、正确使用术语和段落等。

来源：raw/技术/如何写好一篇技术型文档.md

最后更新：2026-06-27

核心原则

1. 搞清楚主谓宾

技术文档的句子结构应清晰明了，谁做了什么事要一目了然。

2. 不滥用代词、过渡词和标点符号

代词过多会让读者混淆指代对象。标点符号应节制使用，每个标点应有其必要作用。

3. 多用强势动词，少用形容词和副词

• 强势动词和主动语句让文档更有力
• 形容词和副词往往增加模糊性，应尽量量化或删除

4. 正确使用术语

专业术语应准确定义并在全文中保持一致。首次使用时应给出解释。

5. 段落设计

• 单一职责：每个段落只讲一个主题
• 好的开头语：段落首句概括全段内容
• 控制长度：段落不宜过长

6. 适当使用列表和表格

列表和表格能将复杂信息结构化呈现，比大段文字更易阅读。

工程师的两大困难

1. 思维方式固化：代码写得多、文字写得少，代码和文字是两种不同的思维方式
2. 表达能力有限：文字表达本身需要刻意练习

相关页面

• 过早优化
• 阅读方法论
• 软件项目管理——文档是项目管理的重要产出
• 视频转文字工作流——内容创作中的文档转换工具