文/蔡学镛数据库
技术文档不少，每种文档都有各自的目的。其中和架构师关系最密切的、甚至架构师应该亲自写的文档是技术白皮书与技术路线图，这两份文档是本次文章的重点。网络
技术白皮书 架构
White Paper衍生自White Book（白皮书），通常也称为白皮书，可是内容更浓缩、更精华。White Paper一般合起来写为Whitepaper。 框架
技术白皮书（Technical White Paper）是官方正式的报告指南，风格介于技术论文和商业杂志文章之间，用来描述大问题和技术解决方案。技术白皮书是经常使用的技术营销的手段之一，它的目的是帮助读者了解技术、作出决策。技术白皮书一般是以PDF文件格式存在，10页左右的篇幅最恰当。 分布式
技术发明者（或拥有者）才能发表技术白皮书。例如，支付宝能够发表“总督系统”技术白皮书（我正在研发的一套CEP系统），但不能够发表Spring框架技术白皮书。支付宝计划走向开放，将来可能会提供开放API，那时候就能够对外推出技术白皮书。 测试
技术白皮书是“技术营销”的文件，适合CTO、技术总监、技术专家之类的高层决策人士阅读，让他们经过“大局观”的方式了解整个技术概况。技术白皮书的重点在于让读者深入理解采用此技术将为他们带来多大的利益。 spa
编写技术白皮书要把握如下重点： 设计
1. 技术白皮书表明官方，因此叙述风格必须具备权威性； 支付宝
2. 良好的技术白皮书一般会附上许多方块图，将技术内部的结构表达清楚，并说明和外部的关系； 资源
3. 若是没法使用示意图时，尽可能使用Bullet Point；
4. 技术白皮书必定要把握重点，不能够长篇大论；
5. 技术白皮书必定要有高技术含量，鸡毛蒜皮的琐碎细节一律不提；
6. 以读者的利益为叙述核心，而非以技术自己的先进或自身的利益为叙述核心。
上面的第6点是大部分技术白皮书的毛病所在，须要特别解释。技术白皮书不该该沦为自言自语、自吹自捧，而是应该从“顾客第一”的角度分析读者有什么问题，须要什么样的技术，而咱们的技术多是一项不错的解决方案，由于咱们是如何如何作到的。
我建议的技术白皮书编写框架以下：
技术路线图
讨论完技术白皮书，接下来看技术路线图（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 审查和更新：要周期性的审查并更新。
总结
本系列文章共四篇，到此已经彻底结束。经过本系列文章，但愿唤醒你们对技术文档的重视。
技术写做的经验培养、技术文档体系的创建，都是须要时间的。身为一个技术人员，若是你认为你正在作的技术是有价值的，你就应该为它创建技术文档，尽管一开始会以为写做很难、也没足够的时间进行写做。公司更应该领悟到，若是没有技术文档，一旦人员更替、新员工加入，或者须要对外推广时，都会遇到至关多的困难。从今天起，让咱们开始重视技术写做能力的培养与技术文档体系的创建。