优秀技术文档规范

w7a8 · 发表于 2008-4-12 23:26:04

拥有准确的技术文档不仅对于公司是非常有益处的，而且也能够让客户从中受益。由于产品如何使用在某种程度上是要依赖技术文档来进行说明的，因此技术文档必须十分的准确可靠。使用不准确的和已经过时的技术文档对于公司的发展也会产生一定的阻碍，同样的，它也会对公司的客户们产生消极的影响。一旦客户发现在他们使用产品的时候遇到了问题，却不能通过求助于伴随产品的技术文档的手段进行解决的时候，客户们就会对这种产品产生怀疑乃至于失去信心，那么，公司的信誉和利益自然而然的就会受到损害。这就是不准确的和过时的技术文档给我们带来的危害。
　　缺乏准确性以及内容晦涩难懂都会让开发新手以及其他的一些技术工作者们对这些技术文档敬而远之，从而不利于他们的学习和掌握。在本篇文章中，我们要讨论的就是如何在你的开发小组中编写出准确而且易于掌握的技术文档。
　　技巧一：制定出一个技术评价核对表
　　许多的程序开发设计者以及管理者都缺乏从技术上评价一个文档的经验。这里有一些方法可以提高这些技术文档的准确性：
　　把注意力集中于技术事实上，这样能够核实这些技术是作为技术文档而被编写出来的。技术评论的工作并不等同于一般的编辑工作。
　　一定要从技术上核实，在技术文档里编写的程序与步骤的准确性。
　　一定要从技术上核实，在技术文档中使用的图片捕捉的准确性。
　　技巧二：一定要在技术文档编写的过程中明确责任
　　技术文档编写不好的一个原因常常是由于对它不够重视。这是由于在编写技术文档的时候，没有十分的明确各种责任。因此，一定要在技术文档编写的过程中明确责任，这些方法包括：
　　在技术文档中加入作者以及相关人员的姓名。一些公司可能有规定，禁止出现员工的姓名，但是在技术文档中包含作者以及相关人士姓名的做法能够促进这些内部员工之间的交流。对于外部的文档使用者，比如为商业现货软件编写的用户指南，可以加入作者以及相关人员的姓名，用以明确和承认他们对开发所做的工作和贡献。
　　把文档的技术评论作为提供给开发设计人员的年度评论的一部分。
　　在项目计划中指派专人负责技术评论的工作。
　　技巧三：增加技术文档编写者的准确性
　　由于技术文档编写者在许多公司内都是非常主观的一个职位，并且编写技术文档也是他们最主要的职责，因此做这些工作的人都必须与他们所编写的技术文档的准确性有着直接的利害关系。
　　管理人员应该为技术文档编写者设置适当的技术准确级别，并要求他们把准确性保持在这一范围之内。由于一些技术文档编写者对于提升自己对于技术的理解总是不太积极主动，因此，增加他们的责任让他们面对更多的压力对项目里的每一个人来说都是有好处的。如果一个技术文档编写者无法达到更高的标准，那么你就需要重新审视一下你的技术文档编写者是否能够满足你们的团队的战略要求，是否能够满足客户们的需要呢？
　　为了帮助技术文档编写者，你需要让他们对于具体的技术有着更深层次的认识，因此，作为管理者，你应该：
　　让技术文档编写者多参加有关产品设计与开发的小组会议。
　　让技术文档编写者参与到技术要求、功能规范以及设计方案的开发工作中去。
　　把技术文档编写者包括进开发小组的邮件列表中去。
　　这技术文档编写的周期，把产品在公司内部进行发布。技术文档编写者很容易变得非常封闭，但是如果把产品在内部首先发布一下，那么就能够给开发人员以及项目管理人员提供一种新的途径来了解以前可能并不容易了解的情况。
　　鼓励技术文档编写者更多的了解有关产品背后所包含的各种技术。举个例子来说，如果你开发基于Java语言的应用软件，那么，就应该鼓励技术文档编写者多多了解Java编程语言，并且尽量让他们能够流畅的掌握这门编程语言。
　　技巧四：设置任务的优先次序
　　通常的情况下，主要的开发设计人员脑海中包含着有关整个项目的信息，而且，有时候还会同时考虑许多其它的项目。即使他或者她的日程安排已经非常的紧张，但是，他们脑海中的产品信息对于确保技术文档编写的准确性来说是非常重要的。
　　当前的形势让我们不得不以更少的资源完成更多的任务，而作为开发设计人员，由于他们工作的特殊性，这些人总是处于紧张而繁忙的状态下。下面是一些技巧，可以帮助你从这些忙碌的开发设计人员哪里获得你所需要的信息，并且保证能让他们的知识给技术文档的编写带来好处：
　　不要让他们从头至尾的审阅技术文档。
　
　　和技术文档的编写者一起确定哪些部分必须让开发设计人员进行审阅。
　　与他们一起利用大段的完整时间来审阅技术文档。
　　如果技术文档的审阅者时间表安排得很紧，那么就给他提供一个具体的列表，在其中明确哪些部分你需要他进行审阅的。并且保证让小组内的其他成员完成剩余部分的审阅工作。技术文档中与审阅者专业技术领域直接相关的部分绝对是需要他进行仔细审阅的。
　　更好的完成审阅工作
　　充分有效的完成技术文档的审阅工作不仅会让外部的用户，也会让内部的用户从中受益。但是，经常会有技术人员认为做这样的工作是没有多大意义的，那么，作为管理者就面对着这样一种挑战，就是要在整个的审阅过程中设置好优先次序从而保证为开发工作所做出的努力获得成功。

上一篇：深入了解软件开发瀑布模型
下一篇：模板集萃