- 浏览: 1051641 次
- 性别:
- 来自: 郑州
文章分类
- 全部博客 (605)
- 数据挖掘 (22)
- spring (40)
- 工具使用 (39)
- java (137)
- JavaScript (40)
- webwork (12)
- web (120)
- 资源 (7)
- SSH (5)
- oracle (20)
- J2ME (1)
- 环境配置 (37)
- 项目管理 (29)
- mysql (14)
- struts (4)
- 项目总结 (27)
- ibatis学习 (33)
- 学习计划 (2)
- 缓存 (7)
- 重构 (3)
- Android (1)
- jquery (12)
- UML (3)
- 用户体验 (4)
- 习惯 (7)
- sakai (1)
- urlrewrite (4)
- rss (5)
- C plus plus (5)
- 算法 (5)
- 海量数据处理 (7)
- office(word、excel) (1)
- 面试题 (3)
- solr (8)
- 大数据 (2)
最新评论
-
hujin19861102:
截图看不见,最后一个webwrok的配置看不见
Ext+Webwork+Json 实现分页表格查询效果 -
蜗牛笔:
弱弱的问一句,要是分出来的词在词典中没有,那么两部分的pos- ...
ICTCLAS 中科院分词系统 -
weipeng1986:
授人予鱼不如授人予鱼,我想问你的是你是怎么总结的。比如第四种情 ...
JAVA中字符串连接效率的测试 -
xiaoqiang2008:
执行两次的原因是什么,好像楼主没弄清楚啊!是不是在web.xm ...
关于Spring中用quartz定时器在定时到达时同时执行两次的问题 -
Kent_Mu:
...
ibatis-dynamic的用法
作者:蔡学镛
在试图建立“技术文档”时,许多人可能会想到“文档模板” 。文档模板的存在究竟是好是坏,因人因事而异。此外我们也应该分清楚:何时应该使用文档模板,何时不要使用文档模板?
使用模板的好处
先来看看使用模板的好处:
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研究所,现任阿里巴巴支付宝架构师,负责新系统的开发。
发表评论
-
正确地kill java进程
2012-03-06 11:36 1361在linux/unix下,你会怎么中止一个java进程? ... -
TOMCAT中可以限制某些IP访问
2012-03-06 11:32 1132找到context区域,如 <context path= ... -
eclipse下svn的分支与合并操作
2011-08-19 14:50 1540原创作品,允许转载,转载时请务必以超链接形式标明文章 原始出处 ... -
eclipse下SVN subclipse插件
2011-08-19 14:42 1220本文目的 让未使用过 ... -
五种应该避免的代码注释
2010-08-10 23:31 931酷壳: http://CoolShell.cn/ ... -
程序员应知——团队精神
2010-08-10 23:16 958大家都知道,现在的软 ... -
程序员应知:你有几种武器
2010-08-08 23:12 978程序员应知:你有几种武器? http://news.cs ... -
这领导当的,你该怎么办?
2010-08-08 23:10 1010公司有一个部门很不 ... -
没人把程序员当回事儿
2010-07-22 00:48 912没人把程序员当回事儿 ... -
IT外企那点儿事(7):做一个优秀的基层【转】
2010-05-23 22:09 818千里之行,始于足下 ... -
优秀的员工究竟应该是你的棋子, 还是应该成为和你同进退的合作伙伴?
2010-05-17 23:04 843优秀的员工究竟应该是你的棋子, 还是应该成为和你同进退的合作伙 ... -
如何能调动团队的积极性[转]
2010-05-16 23:51 1302原文: http://jackyrong.itey ... -
曹重英:技术人员也要打造人脉竞争力[转]
2010-05-11 23:58 894技术人员是最不擅长交际的一群人,很多技术人员认为人际关系比机器 ... -
PPT收藏
2010-04-03 17:49 884http://tiger888.iteye.com/blog/ ... -
谈谈项目例会[转]
2010-03-28 23:18 1388在中小型系统集成公司中,项目的例会是项目团队内部沟通的主要平台 ... -
软件项目可行性分析和需求分析
2010-03-28 23:09 966http://blog.csdn.net/zhoufoxcn/ ... -
技术管理中常见的几个问题
2010-03-28 22:22 942前几天跟朋友聊天时, ... -
团队篇【转】
2010-03-22 22:11 834我一直坚信只有完美的团队,没有完美的个人! ... -
经理人技能摘取
2010-02-07 22:58 959掌控组织:http://blog.csdn.net/qinzh ... -
收藏编码规范
2010-02-03 21:11 0代码规范每家都有, 可发现开发的时候执行力很差. 所以自己小结 ...
相关推荐
java项目文档编写模板—包含项目全流程文档模板(全)java项目文档编写模板—包含项目全流程文档模板(全)java项目文档编写模板—包含项目全流程文档模板(全)java项目文档编写模板—包含项目全流程文档模板(全)java项目...
Java API接口文档模板详解 Java API接口文档模板是Java初学者必须掌握的重要知识点之一。该文档模板提供了详细的接口输入输出定义,旨在帮助前后端开发人员快速了解和使用接口。下面我们将对该文档模板进行详细解释...
CMMI认证文档模板,对于要申请 CMMI的公司会有所帮助
20份产品经理项目管理常用到的文档模板20份产品经理项目20份产品经理项目管理常用到的文档模板.管理常用到的文档模板..20份产品经理项目管理常用到的文档模板.20份产品经理项目管理常用到的文档模板20份产品经理项目...
CMMI3标准文档模板大全(完整)+CMMI3级软件过程改进方法与规范+CMMI3CMMI3标准文档模板大全(完整)+CMMI3级软件过程改进方法与规范+CMMI3CMMI3标准文档模板大全(完整)+CMMI3级软件过程改进方法与规范+CMMI3CMMI3...
java开发详细设计文档模板java开发详细设计文档模板java开发详细设计文档模板java开发详细设计文档模板java开发详细设计文档模板
"软件详细设计文档模板(最全面)" 软件详细设计文档模板是软件开发过程中的重要文件之一,旨在为软件设计和开发提供详细的设计说明和指导。本文档模板涵盖了软件详细设计的各个方面,包括设计目的和范围、术语表、...
软件工程项目开发文档模板(全套). 01.项目需求说明书 02.项目需求规格说明书(全) 03.项目评审报告(模板) 04.系统概要设计说明书 05.系统详细设计说明书 06.系统设计报告评审记录 07.技术测试报告模板范例 08.系统...
接口文档在软件开发中起着至关重要的作用,它定义了不同系统或组件之间的通信规则,确保数据能够准确、高效地传递。以下是一个详尽的接口文档模板及其关键知识点的解析: 1. **接口文档的基本结构** - **接口名称*...
软件概要设计文档模板 软件概要设计文档模板是项目管理文档之一,旨在为软件开发提供指导和规范。...软件概要设计文档模板是软件开发团队不可或缺的工具,能够帮助团队规范化软件设计、提高软件质量和开发效率。
软件开发详细设计文档模板 软件开发详细设计文档模板是软件开发过程中的一份重要文档,是软件开发的关键文档之一。该文档的主要目的是对软件系统的详细设计进行描述和说明,以便于开发团队和项目相关人员对软件系统...
申请计算机软件著作权需要提交的文档模板。中国版权保护中心网站:http://www.ccopyright.com.cn/,需要用谷歌浏览器 注册、登录、填写申请表、打印申请表并加盖公章。总计四份文档: 文档一、网上填好的申请表并...
文档模板、文档模板、文档模板、文档模板
在软件开发过程中,文档起着至关重要的作用,它不仅是团队沟通的桥梁,也是项目管理和质量保证的关键工具。...这些文档不仅适用于大型企业,小型项目或个人开发者同样能从中受益,使软件开发更加专业和规范。
《程序开发功能需求文档模板详解》 在软件开发过程中,一份详尽且规范的功能需求文档是项目成功的关键。本文将深入解析"程序开发功能需求文档模板",并提供相关指导,帮助开发者和项目经理理解如何有效地制定和使用...
Java开发文档模板是Java编程实践中不可或缺的一部分,它旨在提供清晰、规范的代码编写指南,以提高团队间的协作效率,确保代码质量和可维护性。在Java项目中,良好的文档能够帮助开发者理解项目的架构、功能和设计...
文档编写是任何专业领域不可或缺的一项技能,无论是在学术研究、项目管理还是企业工作中,清晰、规范的文档都扮演着至关重要的角色。"文档模板(学习怎样写文档)"这个资源显然是为了帮助那些对文档写作感到困惑或者...
API 接口文档模板详解 API 接口文档模板是指用于描述 API 接口的文档,旨在提供给开发者使用,以便他们更好地理解和使用 API 接口。该模板主要包括接口说明、使用场景、接口调用说明、输入参数说明、请求示例、返回...
3. **接口设计文档**:接口设计文档详细说明了不同组件或系统之间的交互,包括API规范、通信协议和数据格式。这对于多团队协作和系统集成至关重要。 4. **数据库设计文档**:这部分记录了数据库的逻辑结构和物理...