文档模板，天使或恶魔？

作者：蔡学镛

在试图建立“技术文档”时，许多人可能会想到“文档模板” 。文档模板的存在究竟是好是坏，因人因事而异。此外我们也应该分清楚：何时应该使用文档模板，何时不要使用文档模板？

 

使用模板的好处

 

先来看看使用模板的好处：

1、在你毫无头绪时，文档模板具有引导写作的功效。

2、文档模板可以帮助你不会遗漏一些该写的重点（假设该模板已经很完备）。

3、你可以专注写内容，不用分心去管板型（因为模板都已经将这些设置好了）。板型很重要，好的板型有助于阅读。

 

使用模板的缺点

 

当然使用模板也有缺点：

1、你会觉得有义务将模板内的每个章节都填上文字，你认为这样才是一个完备的文档，这导致许多节的内容被填入一些没有太大意义的陈词滥调。

2、这些“杂讯”会造成文档阅读者的困扰。我看到一些PRD（Product Requirement Document，产品需求文档）的内容有数十页，但真正有价值的却只有几页。

3、你觉得只能依照文档模板的规范写，这会造成视野变窄，因为模板钳制了你的思想，让你无法对当前所写的主题进行创新地思考。

4、如果你认为必须根据模板的前后次序填入内容，可能会造成写作的停滞，因为有些小节的内容你无法理解。

 

跳脱模板的框架

我认为，长期使用模板，可能会对知识的组织与创新能力有害。况且，通常“写作的次序”与“展现的次序”会不太一样，模板的次序是“展现的次序”。虽然依据有一定的品质模板写出来的文档，也可以到达合格的标准，但是想要写出高品质的文档，就必须要跳脱模板的框架。

 

这系列关于文档写作的文章，绝对不是展示各种文档的模板，而是着重讨论每个文档的意义、价值和写作重点。有些文档因为相关，所以放在一起讨论。为了方便解说，我虚构出了NewLang、OldLang等技术。

 

首次登场的是下面三种文档：

1、What’ s New in NewLang 3.1

2、NewLang 3.1 Change Log

3、Learning NewLang form OldLang

 

What’ s New in NewLang 3.1

“What’ s  New  in  NewLang 3.1”文档的目的是让NewLang的“旧版本”用户快速更新到“新版本”的知识。“What’ s New  in NewLang 3.1”文档着墨在新旧版本之间的差异，不赘述新旧版相同的部分。写此文档时，要特别注意两点：

1、两个版本之间差异的部分，必须详细说明；

2、两个版本之间相同的部分，除非特殊状况，否则不应该占用任何篇幅。

 

“新版本”是目前最新版本，这方面通常没有问题，但“旧版本”的挑选，必须谨慎。在What’ s New in NewLang 3.1的例子中，用来对照的旧版本有可能是：NewLang 3.0、NewLang 2.6、NewLang 2.0。挑选旧版本有两个原则，重要性依序是：

1、最多人用的旧版本，例 如 ：NewLang 2.6。

2、前一个旧版本，例如：NewLang 3.0。

 

选定好旧版本之后，“What’s New  in NewLang 3.1”文档一开始必须明确地声明，新版本为何，以及对照的旧版本为何。

 

What’s New  in NewLang 3.1必须用各种手段（图、文、源码范例），完整地描述新旧版差异的部分。编排格式比较自由不固定。常见的排列方式：

1、以Enhancement Proposal或Wish List的条目编号排列次序。

2、以对规格书（Specification）所做的修改排列次序。

3、可能会依据异动的对象分不同小节。例如：工具操作的异动、语法的异动、程序库的异动、目录结构的异动。

 

NewLang 3.1 Change Log

 

很多人会把“NewLang 3.1 Change Log”和“What’s New in NewLang 3.1”混淆了，其实两者主要差异如下：

1、Change  Log是条列式，且每个条列都写得相当精简，不会多做说明。而What’ s New in NewLang 3.1必须写得很详细，容易阅读。

2、Change Log一般是累积的，一份Change  Log文档内，会描述多个版本之间渐进的变化。版本越新列在越上面（例如，3.1、3.02、3.01、3.0）。但What’s New则是只挑一个旧版本作为比较对象（例如3.0）。

3、通常只有比较大的版本会有What’s New，小版本不会有。所以不太会看到What’s New in NewLang 3.1.2。

4、What’s New只描述重要的异动，通常不会提对特定Bug的修复（除非是相当严重且知名的Bug）。Change Log则是不管异动是大或是小，都会列出来。

5、Change Log一般是纯文字格式，除了tab和换行，没有其他变化。What’s New的板型变化比较多，可以改变字体，贴图与表格。

 

Learning NewLang  form OldLang

 

Learning NewLang form OldLang或者NewLang  for OldLang Programmers之类的文档，目的是要帮助OldLang的使用者“进化”到NewLang。这样的文档会着重在OldLang和NewLang的差异。

 

OldLang的挑选必须谨慎，挑选原则是：

1、OldLang是NewLang的竞争对手：例如，Java => C#。

2、NewLang的发展受到OldLang的重大影响，例如，Camel => F#。

 

“Learning  NewLang form OldLang”的做法类似于“What’s New in NewLang 3.1”，但有下面的差异：在“Learning NewLang form OldLang”中，NewLang和OldLang一致的部分也必须提，但可以不必使用太多的篇幅。而在“What’s New in NewLang 3.1”中，两个版本一致的部分要省略不提。

 

“Learning NewLang form OldLang”可能是本文章所提到的三种文档中编写难度最高的。我建议下面几点编写原则：

1、一开始先做大局观，强调理念或范式（Paradigm）上的差异。

2、接着条列每个做法的异同之处。重点放在相异之处，但相同之处也要提及。

3、对于容易形成陷阱的差异，不止要提，甚至要特别强调（透过颜色、特殊方块、特殊标记）。

4、微不足道的小差异，可以忽略。

 

Change Log的扩展

 

讨论完这三种文档，其中的Change Log由于牵涉到其他的文档，话题值得再展开讨论。有一些文档容易和Change Log混淆：Release Notes；ReadMe；Feature List。

 

有些公司是不详细区分Release Notes和Change Log，但事实上，这两份技术文档是不同的，不同之处包括了：

1、Release Notes通常是针对“目前版本”与“上个版本”的差异进行条列。Change  Log是“每个版本”之间的差异条列。

2、Release Notes有可能比Change Log对于每个条目的说明更详细一些。

3、如果有提供Change Log，“通常”可以不需要再提供Release Notes。

4、Release Notes会有一些Last Minute的资讯。我们希望每份文档都是文档工程师花许多时间精心编写的，但有时候文档写完了，程序仍有继续修改的可能。如果文档是以印刷的形式存在，那就没有修改的可能，只好推出Release Notes，连同软件放在一起，作为补充说明。

5、早期的软件，经常会附上ReadMe（读我）档案（档名通常为Readme.txt或者Read.me），提及安装与配置的一些“注意事项”（平台兼容的问题、目录的结构、各种文件用途说明等），现在的软件很少会有ReadMe，而是将这些内容并入到Release Notes中。这些原来属于ReadMe的内容，是不可能出现在Change Log中的。

 

Feature List

 

至于Feature List，其实不是技术文档，而是偏市场营销的文档（尽管可能会大量提及技术）。Feature List通常是大方向的特色说明，不会有太多细节描述，也不会特别强调版本。很多时候，Feature List甚至不是一份独立的文档，而只是An Introduction to NewLang（后续文章会提到此文件）的一小节。

 

既然提到Feature List，顺便提两个相关且营销性质更强的文档：Feature Matrix和Data Sheet。Feature Matrix（功能比较表）是表格形式的文档，它有两个作用：一是列出所有功能，以供快速查询。Feature太多的时候，可以依据属性分类。二是比较两个（或多个）产品的功能差异。Data Sheet意思是数据单，说穿了就是Specification（规格书）。它和Specification的区别在于：Data Sheet是营销文件，面向买家；而Specification是技术文件，面向工程师。Data Sheet也经常被合并成为一个单字Datasheet。

 

小结

 

本系列文章共有四篇，这是第二篇，这一次提到了许多技术文档，我希望你可以在读完这篇文章之后，就开始行动，为你的软件产品建立必要的文档。下一期还有更多技术文档要登场，包括了FAQ、Troubleshooting、Quick Start、User’s Guide、Specification、Glossary等，敬请期待。

 

作者简介：

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