设计文档的可读性（1）：为什么要写设计文档并强调其可读性？

本系列文章将分为三篇介绍设计文档的可读性：

1、为什么要写设计文档并强调其可读性

2、设计文档的核心原则：写作三要素和四个要点

3、设计文档的最佳实践

如果你写不清楚，你可能没有想象中那么聪明。

-Kurt Vonnegut Jr

设计文档是对一个技术问题的解决方案的系统性描述。

• 正在开发的软件，其规模是否较大，值得付出额外的编写评审设计文档的时间来降低失败的风险？

• 如果高级工程师无法确保对每一份代码进行代码评审，那么，让他们参与设计评审是否会有更高的回报？

• 某个软件设计决策是模糊的，甚至有争议。是否有必要围绕设计文档在组织上达成共识?

• 是否需要通过设计文档来强调项目中某个横切面问题，如隐私性(Privacy)、安全性(Security)、日志记录？

• 是否有必要写一份文档，来对有关遗留系统的设计问题提供更全局性的分析？

如果以上问题的答案为“是”，就应考虑通过编写设计文档解决。

通过设计文档，我们：

• 在可以低成本迭代的时候，尽早发现设计中的问题。

• 设计左移，代价左移，快速失败（fail fast）。

• 在团队中对设计达成一致。

• 设计的本质是取舍(tradeoff)。几乎所有的架构设计决策都会被挑战，原因之一是：读者并非对所有的取舍都知晓，且与作者达成共识。在设计文档中清晰地列出取舍，有利于帮助读者了解（并认可）你的决策思路，减少被挑战的可能。

• 将资深工程师的经验和思想扩展到整个团队，帮助团队成长。

• 作为作者，可以供资浅工程师学习。

• 作为读者，可以审核资浅工程师的设计并提供建议。

• 形成团队软件设计的一致方式，沉淀团队/公司技术积累。

• 企业的生命力在于知识价值的积累。

（图片来源于网络）

设计文档是需要编写成本的。如果问题的解决方案非常清晰，没有明确的取舍，设计文档中基本都是实现描述，则应该省略设计文档而直接实现。换言之，如果编写设计文档的时间主要消耗在“写”而不是在“思考”上，则这个设计文档可省略。

3.1 设计文档的读写比最高（ROI）

什么是读写比？读写比（内容被所有人阅读花费的时间：内容写作花费的时间）是逐步上升的。通常，设计文档供阅读读的时间往往远多于写的时间。因此，编写设计文档时就更多考虑读者的体验而非作者的体验。为提升设计可读性的时间非常值得投资。

3.2 设计文档不是文学写作

设计文档的目的是为了沟通设计，而不是为了自我表达。

把精力放在如何清晰、简洁地表达，而非放在文采上。

3.3 为读者而写

了解你的读者。

读者是谁？

（在良好的文档分享文化下）读者不应该只是你的 TL 以及该设计文档的实施者；你的设计文档实际读者的范围往往大得多。在不确定的时候，经验做法是，假设的读者群体为：公司内部的、有一定工程经验的、但对该系统的上下文只有初步了解的软件工程师。

通常，设计文档的范围越大，假定的受众群也会更大。这意味着受众对目标系统的平均了解程度更低，也就意味着设计文档往往需要：

• 更加详细的背景介绍。

• 更少使用内部术语或缩写。

• 更多阐述设计思路、取舍，更少解释具体实现细节。

读者如何阅读？ 

大部分读者不会逐字逐句阅读你的设计文档。大家都很忙。读者通常只会扫描大体结构，然后阅读（或者跳读）自己感兴趣的部分。 

读者喜欢“故事”。将内容以故事的结构呈现最容易被接受，即使我们并不是需要讲述一个传统的打怪升级的故事。虽然故事内容各有不同，但大部分故事都遵循一些基本的范式。例如，约瑟夫·坎伯（https://zh.wikipedia.org/wiki/%E7%B4%84%E7%91%9F%E5%A4%AB%C2%B7%E5%9D%8E%E4%BC%AF） 总结提出全世界大部分神话故事都符合“英雄之旅”（https://zh.wikipedia.org/zh-hk/%E8%8B%B1%E9%9B%84%E6%97%85%E7%A8%8B） -- “启程、启蒙、归程”三幕 -- 这个模式。

就设计文档/科技论文写作而言，通用安全的选择是 Writing Science 所介绍的 OCAR 故事结构。

• Opening：开场，背景介绍。

• Challenge：挑战，所要解决的问题。

• Action：行动，执行的实验/设计/...

• Resolution：结果。

设计文档通常遵循特定的组织结构，我们可以将每一个结构对应到 OCAR 的不同部分，以此讲述故事。

3.4 设计文档 Readability vs. 代码 Readability

都称作可读性，两者有些共通之处：

• 文档着重强调的内容应该是并非显而易见的事项：

• 没有绝对的正确答案：没有完美的代码，也没有完美的设计文档。

• 不同的读者对可读性的理解有细微的不同。可读性是主观的。

• 在实践中，我们追求让更多（而非所有）读者更顺畅地阅读设计文档。

• 我们的目标是有意识地提高文档写作/代码水平。高质量的写作是一种习惯。提高水平的方法有：

• 多读他人优秀的设计文档。

• 评审（Design doc review/Code review）有益。

• 设计文档评审往往主要关注系统设计合理性，但是可读性方面的评审也有必要。

• 多写作、多修改、多重写。

乔梁老师开课啦~视频课程《持续部署训练营（Python版）》， 限时特价！

你的软件开发效率够高吗？质量够好吗？你的团队多长时间才能向用户实时推送一个生产变更？你的软件在发布时，你是否因担心软件交付质量而感到压力倍增？你是否遇到过部署失败，甚至导致停机的情况？持续部署可以帮助你消除软件交付的痛苦，让你能专注于为客户高价值的需求，而不会因为这些交付执行类问题而花太多精力。本课程通过学练结合，理论结合实战，让你体验如何使用构建-测试-部署管道，进行持续部署。并练习如何在有效监控部署的同时，逐步发布功能特性，并作数据库结构变化。

（扫码订阅）