`

文档模板,天使或恶魔?

阅读更多

作者:蔡学镛


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


 

使用模板的好处


 

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

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研究所,现任阿里巴巴支付宝架构师,负责新系统的开发。

分享到:
评论

相关推荐

    java项目文档编写模板—包含项目全流程文档模板(全)

    java项目文档编写模板—包含项目全流程文档模板(全)java项目文档编写模板—包含项目全流程文档模板(全)java项目文档编写模板—包含项目全流程文档模板(全)java项目文档编写模板—包含项目全流程文档模板(全)java项目...

    java的API接口文档模板

    Java API接口文档模板详解 Java API接口文档模板是Java初学者必须掌握的重要知识点之一。该文档模板提供了详细的接口输入输出定义,旨在帮助前后端开发人员快速了解和使用接口。下面我们将对该文档模板进行详细解释...

    CMMI模板.zip_cmmi_cmmi文档_cmmi模板_文档模板_文档模板 cmmi

    CMMI认证文档模板,对于要申请 CMMI的公司会有所帮助

    20份产品经理项目管理常用到的文档模板.zip

    20份产品经理项目管理常用到的文档模板20份产品经理项目20份产品经理项目管理常用到的文档模板.管理常用到的文档模板..20份产品经理项目管理常用到的文档模板.20份产品经理项目管理常用到的文档模板20份产品经理项目...

    CMMI3标准文档模板大全(完整)+CMMI3级软件过程改进方法与规范+CMMI3

    CMMI3标准文档模板大全(完整)+CMMI3级软件过程改进方法与规范+CMMI3CMMI3标准文档模板大全(完整)+CMMI3级软件过程改进方法与规范+CMMI3CMMI3标准文档模板大全(完整)+CMMI3级软件过程改进方法与规范+CMMI3CMMI3...

    java开发详细设计文档模板

    java开发详细设计文档模板java开发详细设计文档模板java开发详细设计文档模板java开发详细设计文档模板java开发详细设计文档模板

    软件详细设计文档模板(最全面).doc

    "软件详细设计文档模板(最全面)" 软件详细设计文档模板是软件开发过程中的重要文件之一,旨在为软件设计和开发提供详细的设计说明和指导。本文档模板涵盖了软件详细设计的各个方面,包括设计目的和范围、术语表、...

    软件工程项目开发文档模板(全套).zip

    软件工程项目开发文档模板(全套). 01.项目需求说明书 02.项目需求规格说明书(全) 03.项目评审报告(模板) 04.系统概要设计说明书 05.系统详细设计说明书 06.系统设计报告评审记录 07.技术测试报告模板范例 08.系统...

    接口文档模板.docx

    接口文档在软件开发中起着至关重要的作用,它定义了不同系统或组件之间的通信规则,确保数据能够准确、高效地传递。以下是一个详尽的接口文档模板及其关键知识点的解析: 1. **接口文档的基本结构** - **接口名称*...

    2-软件概要设计文档模板.docx

    软件概要设计文档模板 软件概要设计文档模板是项目管理文档之一,旨在为软件开发提供指导和规范。...软件概要设计文档模板是软件开发团队不可或缺的工具,能够帮助团队规范化软件设计、提高软件质量和开发效率。

    软件开发详细设计文档模板

    软件开发详细设计文档模板 软件开发详细设计文档模板是软件开发过程中的一份重要文档,是软件开发的关键文档之一。该文档的主要目的是对软件系统的详细设计进行描述和说明,以便于开发团队和项目相关人员对软件系统...

    计算机软件著作权文档模板

    申请计算机软件著作权需要提交的文档模板。中国版权保护中心网站:http://www.ccopyright.com.cn/,需要用谷歌浏览器 注册、登录、填写申请表、打印申请表并加盖公章。总计四份文档: 文档一、网上填好的申请表并...

    文档模板、文档模板、文档模板、文档模板

    文档模板、文档模板、文档模板、文档模板

    软件开发文档模板合集

    在软件开发过程中,文档起着至关重要的作用,它不仅是团队沟通的桥梁,也是项目管理和质量保证的关键工具。...这些文档不仅适用于大型企业,小型项目或个人开发者同样能从中受益,使软件开发更加专业和规范。

    程序开发功能需求文档模板.docx

    《程序开发功能需求文档模板详解》 在软件开发过程中,一份详尽且规范的功能需求文档是项目成功的关键。本文将深入解析"程序开发功能需求文档模板",并提供相关指导,帮助开发者和项目经理理解如何有效地制定和使用...

    Java开发文档模板

    Java开发文档模板是Java编程实践中不可或缺的一部分,它旨在提供清晰、规范的代码编写指南,以提高团队间的协作效率,确保代码质量和可维护性。在Java项目中,良好的文档能够帮助开发者理解项目的架构、功能和设计...

    文档模板(学习怎样写文档)

    文档编写是任何专业领域不可或缺的一项技能,无论是在学术研究、项目管理还是企业工作中,清晰、规范的文档都扮演着至关重要的角色。"文档模板(学习怎样写文档)"这个资源显然是为了帮助那些对文档写作感到困惑或者...

    api接口文档模板

    API 接口文档模板详解 API 接口文档模板是指用于描述 API 接口的文档,旨在提供给开发者使用,以便他们更好地理解和使用 API 接口。该模板主要包括接口说明、使用场景、接口调用说明、输入参数说明、请求示例、返回...

    软件开发文档模板

    3. **接口设计文档**:接口设计文档详细说明了不同组件或系统之间的交互,包括API规范、通信协议和数据格式。这对于多团队协作和系统集成至关重要。 4. **数据库设计文档**:这部分记录了数据库的逻辑结构和物理...

Global site tag (gtag.js) - Google Analytics