Diátaxis2 months agohttps://diataxis.fr/Diátaxis 是一种系统化的技术文档撰写方法，专注于内容、架构和形式。它识别出四种不同的用户需求及对应的文档类型：教程、操作指南、技术参考和解释。该框架解决了写什么、如何写以及如何组织文档的问题。它轻量、易于理解，且不施加实现限制，使用户和维护者都受益。Diátaxis 已被许多项目成功采用，Vonage、Gatsby 和 Cloudflare 等公司的推荐信证明了这一点。
Writing a good design document2 months agohttps://grantslatton.com/how-to-design-document设计文档是技术报告，概述了带有权衡和约束的实现策略。目标是说服读者（以及作者）该设计是最优的，类似于数学证明。良好的组织至关重要；确保每个句子从前一句逻辑流畅地衔接，避免“意大利面条式设计文档”。预见读者的反对意见并预先解决，以引导他们的理解。无情地编辑以删除不必要的词语；目标是在不丢失信息的情况下从初稿中删除约30%的内容。大量练习；亚马逊的文档编写文化（使用红笔进行无声阅读）迫使改进。使用短段落，每段一个想法，使读者能够在短期记忆中压缩信息。在附录中包含复杂的计算或模拟，保持主体内容简洁易懂。实际示例展示了如何将冗长的文本编辑为传达相同信息的简洁版本。