架构师看重的文档.docx

文/蔡学镛 技术文档很多，每种文档都有各自的目的。其中和架构师关系最密切的、甚至架构师应该亲自写的文档是技术白皮书与技术路线图，这两份文档是本次文章的重点。 技术白皮书 White Paper 衍生自 White Book（白皮书），一般也称为白皮书，但是内容更浓缩、更精华。White Paper 通常合起来写为 Whitepaper。 技术白皮书（Technical White Paper）是官方正式的报告指南，风格介于技术论文和 商业杂志文章之间，用来描述大问题和技术解决方案。技术白皮书是常用的技术营销的手段 之一，它的目的是帮助读者了解技术、做出决策。技术白皮书通常是以 PDF 文件格式存在， 10 页左右的篇幅最恰当。 技术发明者（或拥有者）才能发表技术白皮书。例如，支付宝可以发表“总督系统”技术白皮书（我正在研发的一套 CEP 系统），但不可以发表 Spring 框架技术白皮书。支付宝计划走向开放，未来可能会提供开放 API，那时候就可以对外推出技术白皮书。 技术白皮书是“技术营销”的文件，适合CTO、技术总监、技术专家之类的高层决策人士阅读，让他们通过“大局观”的方式了解整个技术概况。技术白皮书的重点在于让读者深刻理解采用此技术将为他们带来多大的利益。 编写技术白皮书要把握以下重点： 技术白皮书代表官方，所以叙述风格必须具有权威性； 良好的技术白皮书通常会附上许多方块图，将技术内部的结构表达清楚，并说明和外部的关系； 如果无法使用示意图时，尽量使用 Bullet Point； 技术白皮书一定要把握重点，不可以长篇大论； 技术白皮书一定要有高技术含量，鸡毛蒜皮的琐碎细节一概不提； 以读者的利益为叙述核心，而非以技术本身的先进或自身的利益为叙述核心。 上面的第 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.1 中，条件包含技术路线图所需、来自组织不同部门（营销、开发、战略等部门）的输入，这些部门有着不同的计划区间（Planning Horizon）和不同的看事情角度。如果条件不满足，则要采取行动来满足条件。条件都满足了，才能继续下一个步骤。 步骤 1.2 的意思是：技术路线图的建立牵涉到时间和各种资源，必须要有坚定的领导权威。领导权威必须来自参与者之一，由参与者之一赋予领导权威或地位。让组织驱动此过程， 并使用此路线图来进行资源分配的决策。 在步骤 1.3 中，指定好路线图的环境背景。一家公司应该要有清晰的愿景（Vision）， 且技术路线图应该要能清楚地支持此愿景。如果愿景不存在，那么应该