Technical Writing

Internal Technical Writing

Overview

Use this skill when the writing target is an internal技术方案、评审稿、架构说明、分享文稿，重点在于把背景、猜想、证据、抽象、实现影响面讲清楚。

这类写作更接近技术汇报，不是宣传稿，也不该写成散文。语气要平稳，判断要有来路，段落要能顺着问题往下读。

When to Use

• 在写内部技术方案、设计说明、评审文档、分享稿
• 在改一篇已经有内容、但文风过满、结论过快、证据不足的技术文章
• 在解释代码、模块边界、架构演进、可观测性、评测方法
• 在把聊天记录、讨论结论整理成可传播的技术文档

When not to use

• UI 文案、按钮文案、产品营销稿
• 面向外部用户的帮助文档
• 纯粹的 API reference 或机械说明书

Core Stance

先接住读者，再往下解释。

常见写法是作者替读者抢先下判断，像 很清楚、说明了、显然、真正。这里更适合换成三步：

1. 我们观察到了什么
2. 基于这些观察，可以归纳出什么
3. 这些归纳暂时更适合落在哪类实现或组织方式里

如果要给出更强的判断，至少满足下面任一条件：

• 前文已经提出了对应的猜想，这一段是在 callback
• 同一段上下文里已经有交叉验证的 evidence
• 已经引用了具体模块、代码、issue、trace、指标或实验结果

这些 bad case 往往有同一种共性：

• 句子承担的是“主持文章”的功能，不是“推进论证”的功能
• 句子在表达作者感受，不是在交代条件、对象、约束或判断
• 句子把英文抽象写作习惯直接投到了中文里
• 句子删掉以后，不影响事实，不影响论证，也不影响结构