10技巧创建软件开发文档

虽然编制文档并不是众多IT专业人员选择职业的真正原因，但是足够的激情、勤奋工作和注意细节将会使你成为老板的一份更具价值的资产并能够提升你的履历。

本文我们介绍了取自10 Things博客中的文章《创建软件文档的10项技巧》。该博客主要面向应用开发专业人员，但是项目经理和管理人员也可以从他们的智慧中获益。

Alan Norton从事软件系统开发和相应软件项目文档编制工作很多年。我们可以从他的多年从业经验中获益。

坦白地讲，没人想写，没人想读或者实际上是不得不作这项工作。我想说的是软件开发中的文档编制，通常定义为软件生存期的倒数第二步。虽然编写文档可以而且应该出现的软件生存期的任何阶段，但是本文我们将集中在文档编制阶段。需要注意的是我们要讨论的文档包括两部分：终端用户文档和系统/内部文档。

项目生存期

在准备这篇文章而做一些研究时，我找出了Petrocelli/Charter 1976年出版的Anthony Ralston 和 Chester L.Meek编辑的计算机科学百科全书。可以明确地是这是第一版的经典，但是有一些东西是永恒的，其中在文档词条关于文档的描述为：

“文档是开发和应用基于计算机的系统的重要部分。在一些商业组织，20%到40%的开发工作量用于新系统的文档编制，其中记录了新系统是如何工作的以及是如何开发的。”作者K.R.London。

我对于这个定义在今天的正确性感到好奇，如果是真的话，那么为什么媒体没有给与文档应该的关注。在项目生存期我们找不到很多关于文档花费的信息（如图A）。我猜测可能是这些花费经常被低估或没有进行合理的收集。从事工作系统开发的IT专业人员，很多可能会将文档的实际花费看作是件尴尬的事或者认为这反映了他们不良的生产率和工作。

对项目生存期文档阶段的重要性的看法，可能依赖于你在IT组织的角色。如果你是经理或项目小组组长，那么你会认为文档对于项目的成功是十分重要的。如果你处于一个非管理职位，那么你会认为编制文档是件恼人的麻烦事，因为它妨碍了你的实际工作。尽管下文的10项技巧主要面向后一类人员，但是项目经理和管理人员同样也可以从中获益。

图 A

7步项目生存期来源：WikipediA