蔡学镛 架构师最重视的文档

文/蔡学镛

 

 

技术文档很多，每种文档都有各自的目的。其中和架构师关系最密切的、甚至架构师应该亲自写的文档是技术白皮书与技术路线图，这两份文档是本次文章的重点。

 

 

技术白皮书

White Paper衍生自White Book（白皮书），一般也称为白皮书，但是内容更浓缩、更精华。White Paper通常合起来写为Whitepaper。

技术白皮书（Technical White Paper）是官方正式的报告指南，风格介于技术论文和商业杂志文章之间，用来描述大问题和技术解决方案。技术白皮书是常用的技术营销的手段之一，它的目的是帮助读者了解技术、做出决策。技术白皮书通常是以PDF文件格式存在，10页左右的篇幅最恰当。

技术发明者（或拥有者）才能发表技术白皮书。例如，支付宝可以发表“总督系统”技术白皮书（我正在研发的一套CEP系统），但不可以发表Spring框架技术白皮书。支付宝计划走向开放，未来可能会提供开放API，那时候就可以对外推出技术白皮书。

技术白皮书是“技术营销”的文件，适合CTO、技术总监、技术专家之类的高层决策人士阅读，让他们通过“大局观”的方式了解整个技术概况。技术白皮书的重点在于让读者深刻理解采用此技术将为他们带来多大的利益。

编写技术白皮书要把握以下重点：

1. 技术白皮书代表官方，所以叙述风格必须具有权威性；

2. 良好的技术白皮书通常会附上许多方块图，将技术内部的结构表达清楚，并说明和外部的关系；

3. 如果无法使用示意图时，尽量使用Bullet Point；

4. 技术白皮书一定要把握重点，不可以长篇大论；

5. 技术白皮书一定要有高技术含量，鸡毛蒜皮的琐碎细节一概不提；

6. 以读者的利益为叙述核心，而非以技术本身的先进或自身的利益为叙述核心。

上面的第6点是大部分技术白皮书的毛病所在，需要特别解释。技术白皮书不应该沦为自言自语、自吹自捧，而是应该从“顾客第一”的角度分析读者有什么问题，需要什么样的技术，而我们的技术可能是一项不错的解决方案，因为我们是如何如何做到的。

我建议的技术白皮书编写框架如下：

封面：技术名称、缩写、版本；公司名称、Logo；文档日期。
不需要目录，因为文档不长，没有必要提供目录。
内容：依据上面述的六个重点编写，格式自由安排。下面是建议内容：
摘要（约中文三百字的摘要）
简介（What、Why、How等）
技术说明（架构等）
Summary（总结）
文档的法律声明
技术路线图

讨论完技术白皮书，接下来看技术路线图（Technology Roadmap）。

想要到达某个目标，可能不是一蹴而就的事，需要有路线规划，让大家一目了然地知道近期、中期、远期的目标，这就是Roadmap（路线图）。Roadmap也可以写成Road Map。

Roadmap应用相当广泛：两岸想统一，需要Roadmap；支付宝想要创造100倍的业绩，需要Business Roadmap。如果过程涉及技术，那么这就是Technology Roadmap。只有新产品、新兴技术、相当复杂的产品可以有Technology Roadmap。如果仅是对产品做小改进，根本不需要Technology Roadmap。

技术路线图有三个主要用途：

是一种规划，帮助决定出一组需求，以及满足此需求的技术；
是一种机制，可以帮助预测技术开发与走向；
是一种框架，可以用来帮助计划与协调技术的开发。
随着软件产业越来越成熟，产品经理（Product Manager）也变成必备的职位。产品经理要负责整个开发过程的管理，在此过程中，制定产品路线可以帮助软件产品经理规划与分配资源。

制定技术路线图分三个阶段：

1. 第一阶段：初步行动；

2. 第二阶段：技术路线图开发；

3. 第三阶段：后续行动。

可以看出第一阶段是准备，第二阶段是重点，第三阶段是后续跟踪修改。

在第一阶段（初步行动），关键决策者发现他们有一个问题需要解决，而需要一份技术路线图来帮助他们解决此问题，他们要这样做：

1.1 满足根本条件；

1.2 赋予领导权威或地位；

1.3 定义技术路线范围和边界。

在步骤1.1中，条件包含技术路线图所需、来自组织不同部门（营销、开发、战略等部门）的输入，这些部门有着不同的计划区间（Planning Horizon）和不同的看事情角度。如果条件不满足，则要采取行动来满足条件。条件都满足了，才能继续下一个步骤。

步骤1.2的意思是：技术路线图的建立牵涉到时间和各种资源，必须要有坚定的领导权威。领导权威必须来自参与者之一，由参与者之一赋予领导权威或地位。让组织驱动此过程，并使用此路线图来进行资源分配的决策。

在步骤1.3中，指定好路线图的环境背景。一家公司应该要有清晰的愿景（Vision），且技术路线图应该要能清楚地支持此愿景。如果愿景不存在，那么应该先发展出一个愿景，并清晰地描述它。当做到这一点，路线图的边界与范围就能够被定义出来。此外，还要设定好计划区间和详细程度。

完成了第一阶段的初步行动，接下来就可以进行第二阶段，真正把技术路线图开发出来。第二阶段可以分成七个步骤，下面依次描述。

2.1 找出路线图焦点的产品：在本步骤中，找出共通的产品需求，且所有的参与者对此达成共识。让所有的人都能接受此步骤相当重要。如果有不确定的地方，可以采用场景规划（scenario-based planning）的方式，找出共通的产品需求；

2.2 找出关键的系统需求以及它们的目标：一旦决定好，这些需求要被设定路线，然后关键的系统需求就可以被辨识出来。关键的系统需求为技术路线图提供整体的框架。这里的需求可以有一些目标（例如高稳定性、低成本）；

2.3 指定主要的技术领域：想实现此关键的系统需求，有一些相关的领域。对于每个技术领域而言，有一些技术在其中。技术领域包括分布式数据库、网络、系统开发、财务会计等；

2.4 指定技术者和他们的目标：在此步骤中，来自步骤2.2的关键系统需求会被转换成某技术领域中具有目标的技术驱动者（technology driver）。这些驱动者会影响那些技术方案被选用。驱动者依赖于技术领域，但是与“技术如何因应系统需求”有关；

2.5 找出技术方案与它们的时间线：此时技术驱动者和它们的目标已经被指定好，且“满足目标的技术方案”应该也被指定好。对于每个技术方案，都应该估计出一个时间线，说明它会如何成型，以符合技术驱动者的目标。某些特定的状况下，要考虑到时间。电子商务或软件开发的区间通常会比较短；

2.6 建议应该采用的技术方案：因为不同技术方案的成本、时间线等条件可能不同，所以要从中做选择。在这个步骤，要根据目标做取舍（例如：效能比成本重要）；

2.7 建议技术路线图报告：此时技术路线图已经完成。技术路线报告包含五个部分的内容（当然，此报告也可以包含其他额外的资讯）：

每个技术领域的识别与描述；
路线图的关键因素；
未处理的领域；
实践的建议；
技术建议。
完成了2.1~2.7的七个步骤，技术路线图就已经开发出来了。软件开发出来并不代表结束，还需要后续的测试、运营、维护等。同理，技术路线图开发出来之后（第二阶段），还需要后续的动作（第三阶段）。

第三阶段大致分为三个步骤：

3.1 讨论和验证路线图：路线图需要被批评、验证、采用；

3.2 制订一个执行计划：要依据技术路线图设计出一个计划；

3.3 审查和更新：要周期性的审查并更新。

 

总结

本系列文章共四篇，到此已经完全结束。通过本系列文章，希望唤醒大家对技术文档的重视。

技术写作的经验培养、技术文档体系的建立，都是需要时间的。身为一个技术人员，如果你认为你正在做的技术是有价值的，你就应该为它建立技术文档，尽管一开始会觉得写作很难、也没足够的时间进行写作。公司更应该领悟到，如果没有技术文档，一旦人员更替、新员工加入，或者需要对外推广时，都会遇到相当多的困难。从今天起，让我们开始重视技术写作能力的培养与技术文档体系的建立。

 

作者简介：

蔡学镛，台湾台南人，毕业于台湾清华大学Computer Science研究所，现任阿里巴巴支付宝架构师，负责新系统的开发