Writing a good design document
a day ago
- 设计文档是技术报告，概述了带有权衡和约束的实现策略。
- 目标是说服读者（以及作者）该设计是最优的，类似于数学证明。
- 良好的组织至关重要；确保每个句子从前一句逻辑流畅地衔接，避免“意大利面条式设计文档”。
- 预见读者的反对意见并预先解决，以引导他们的理解。
- 无情地编辑以删除不必要的词语；目标是在不丢失信息的情况下从初稿中删除约30%的内容。
- 大量练习；亚马逊的文档编写文化（使用红笔进行无声阅读）迫使改进。
- 使用短段落，每段一个想法，使读者能够在短期记忆中压缩信息。
- 在附录中包含复杂的计算或模拟，保持主体内容简洁易懂。
- 实际示例展示了如何将冗长的文本编辑为传达相同信息的简洁版本。