`

文档模板,天使或恶魔?

阅读更多

作者:蔡学镛


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


 

使用模板的好处


 

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

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项目...

    restful接口文档模板

    ### RESTful接口文档模板知识点解析 #### 一、RESTful接口概述 REST(Representational State Transfer)是一种网络应用程序的设计风格和开发方式,基于HTTP协议,可以使用XML或者JSON格式传输数据,一般用于...

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

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

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

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

    java开发详细设计文档模板

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

    接口文档模板.docx

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

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

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

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

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

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

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

    Java开发文档模板

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

    服务器接口对接文档模板

    服务器接口对接文档模板是后台服务器服务于客户端的接口对接说明文档,内容洁净、详细、言简意赅,可自定义或丰富其内容。该文档是后台服务器开发人员不可缺少的好文档。 知识点1:服务器接口对接文档模板的作用 ...

    api接口文档模板

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

    开发文档模板(全).zip

    "开发文档模板(全).zip"这个压缩包提供了一系列完整的开发文档模板,涵盖了软件生命周期的各个阶段。下面将详细解释这些模板及其在开发中的应用。 1. 需求规格说明书模板:这是项目开始时的关键文档,它详细描述...

    文档模板大全(包含16种常用文档模板)

    包含文档模板如下: 操作手册.doc 测试分析报告.doc 测试计划.doc 概要设计说明书.doc 开发进度月报.doc 可行性研究报告.doc 模块开发卷宗.doc 软件设计文档.doc 软件需求说明书.doc 数据库设计说明书.doc...

    开发文档模板[全套].zip

    系统设计文档描述了软件的整体架构和模块划分,由项目经理或高级开发者编写。它包含系统架构图、数据库设计、接口规范等,为后续的编码工作提供指导。程序员可根据设计文档进行模块开发,确保各个组件之间的协同工作...

    软件开发文档模板(最全)

    本文将深入探讨“软件开发文档模板(最全)”所涵盖的几个核心部分:需求文档、设计文档和开发文档,以及它们如何在软件生命周期中发挥作用。 1. **需求文档**: - 需求分析报告:详细描述软件应实现的功能和非...

    模板文档毕业论文模板.docx-模板文档模板文档模板文档模板文档

    模板文档毕业论文模板.docx-模板文档模板文档模板文档模板文档 毕业设计(论文) 论文题目: 系 别: 专业班级: 学生姓名: 指导教师: 二○○ 年 月 日 目XX录(三号黑体加粗,居中) 摘XX...

    数据字典文档模板

    数据字典文档模板 在软件开发和数据库管理中,数据字典文档模板扮演着非常重要的角色。它是记录和描述数据库设计的重要文档,是数据库管理员和开发者之间的重要沟通工具。下面是关于数据字典文档模板的详细知识点:...

Global site tag (gtag.js) - Google Analytics