Question

各位在写文档时都注意了哪些点呢？另外，要想写出一篇有用的文档，有哪些点需要注意呢？

文档是有读者的。如果在写文档时没有考虑读者，那我们的意识就会偏到“应该加入哪些信息”“应该写到哪种程度”上，结果就是相关信息越添越多，最后却忘了原本要表达的信息，导致文档不能达到原定的目的。能让读者觉得是好文档的文档，必然考虑了“读者是谁”以及“怎样写能让读者看得更明白”等问题，确保为读者提供了充足且有用的内容。

文档的目标读者、内容、深度等问题，可以拿过去项目的文档来参考。我们知道，“文档的写法”“版本库的用法”“项目的推进放法”这类东西都是可以重复利用的。同样道理，一个项目文档的许多元素完全可以拿到另一个文档中重复利用。

7.4.1　什么是文档集

如今有一种思路，就是为了重复利用文档而将文档模板化，然后构建成文档集（Documentation Portfolio）。《Python 高级编程》5 一书将文档集称为文档工件集，并作出如下定义。

5 原书名为 Expert Python Programming ，Tarek Ziadé 著，姚军等译，人民邮电出版社，2010 年 1 月。——译者注

从作者的角度，这可以通过拥有一组可复用的模板和描述如何、何时在项目中使用这些模板的指南来完成，它被称为文档工件集。

也就是说，一个文档集由以下内容构成。

· 文档模板集（规则、流程、会议记录、设计等）

· 使用文档模板的导航（何时用、怎样用等说明）

7.4.2　项目所需文档的一览表

Scoot Ambler 著的《敏捷建模：极限编程和统一过程的有效实践》一书中有文档集的相关信息，可供各位参考。他在书中提到了项目所需的文档一览表，同时举了例子，现整理如下。

· 文档一览表（精选）

o 协议模型：关于系统的技术性界面

o 设计上的已确定事项：设计和架构方面的重要决定的记录

o 对上级的概要说明：系统构想、需求、当前的预估、风险、人员计划、日程安排

o 使用文档：使用时所需信息、流程、环境的概述

o 项目概要：开发时所需信息、流程、环境的概述

o 需求文书：定义系统需要完成的目标

o 支持文档：给技术支持者的培训资料、问题排查、维护团队的联络方式一览表等

o 系统文档：系统概要、构架、需求事项等的概要

o 用户文档：使用说明书、培训资料等

敏捷建模的文档列表基本网罗了所有必备信息。但这仍存在一些问题，比如从完全没有文档的状态起步时，我们很难一次性将这些文档全写出来。所以第一步，可以先处理自身团队或组织所需的部分，或者是以过去的文档为基础，将文档的目的抽选出来进行类似上述分类，进而模板化。最终我们将构筑出适用于自己或团队的文档集，供我们在今后的项目中加以利用。

接下来，我们将根据目标读者的类型分别了解一下文档集。

7.4.3　面向项目组长、经理

普通程序员很难想象项目组长、经理们想要的信息，所以更谈不上将它们写入文档。这里最好的办法就是向项目组长、经理询问具体想要的信息。各位不妨以本节所讲的内容为基础，跟项目组长、经理探讨一下访问客户之前应该掌握哪些信息，应该将哪些东西落实在文档中。

◉ 项目的目标（终点）

在项目目标中，我们要写出“用户导入我们即将开发的系统后能获取何种收益”“与以往相比有哪些改善”之类的信息，而技术和系统方面的目标则不必在此太过重视。当然，有些项目本身就是为了开发 Python 程序库，这时技术和系统方面的目标就成了必须写入目标的事项。不过，这种情况也必须写清楚为什么要开发这个东西。

项目的目标（终点）自然应该跟所有参与项目的成员共享，但意外的是，这一点在现实中贯彻得并不好。即便团队中某些成员只负责敲代码，我们也应该把目的共享给整个团队。更何况，在文档中写明目标对项目组长本身也有帮助。或许尚不熟悉项目运营的组长会觉得“目标会经常跟着客户的要求变”，但实际看来，目标真正改变的项目并不多。我们不光要询问客户的要求，还要将目标落实到字面上，然后跟客户以及项目组成员共享出来，这样才能给项目创造出一个主干，使开发有条不紊。如果这一点上搞不清楚，那这个项目从头至尾都不会稳定，难免发生差错，甚至会导致返工。

◉ 体制

在项目的体制中，要写明各个参与者（团队）的职务，使成员们清楚自己在项目中的定位。职务不能只写名称，还要写明各职务需要做的工作，让人明白每个职务该负起哪些责任。如果只写一个“主程序员”，那么任谁都搞不清楚这个职务应该负责什么。这部分虽然不必写得很严密，但必须让每个职务对应的人员清楚自己的职责范围，不然项目开发的过程中必定出现大问题。另外，某些职务或团队的人数需要根据参与时期进行调整，这类信息最好也写进来。

◉ 需求

需求是很重要的。在项目开始之前，需求就已经朦胧地存在于客户脑中了。我们的设计与开发全都要以需求为准。在开发过程中，需求是考察系统完成度的指标，如果需求不明确，我们完全无法判断系统的发展方向是否正确，也无法考察开发到了哪里。到了运营阶段，我们也需要参考需求来了解系统的概念或衡量业务变更的影响。

在定义需求时，一般要将需要哪些功能、需要怎样运营、需要运行性能达到何种程度等信息逐条列出或者汇总成表。

◉ 日程、咨询项目表

对实现需求的日程进行描述。能左右日程的因素有很多，比如客户的要求、当前可处理的范围、能影响到日程的外部因素，等等。在初期阶段，日程常会受各种因素影响而变化，所以要定期重新审视并做好记录。

除此之外还有咨询项目表，用来与客户协商尚不明确的事宜。

7.4.4　面向设计者

面向设计者的文档需要对构架和概念多加描述，但随着时间推移，选择该设计、基础结构、开发语言的理由会显得越来越重要，所以这些也要写在文档中。另外，在 OS 和开发语言方面，最好也写上选择该版本的理由。以 Python 为例，假设我们选用了较旧的 2.5 版，理由可能是只有这个版本提供了我们用作基础结构的服务，也可能是当时没有发布新版本，或者是 OS 的程序包管理中没有新版本，又或者是公司的方针规定不采用最初的主版本，总之可能的情况非常之多。如果文档中没有对这些情况做记录，一旦将来要探讨版本变更问题，那将会是一件非常麻烦的事。

涉及下列各项时，请各位务必记录选择的理由。

· OS、语言、版本的选择

· 构架设计

· 基础设施设计

7.4.5　面向开发者

在搭建开发环境方面，我们提倡导入自动化机制来尽量缩短流程，但还是难免会遇到无法自动化的部分，或者是自动化成本过高的情况。因此，我们应该将流程尽量详细地记录下来，以备不时之需。有些时候，流程文档的记录会不够全面，比如只写了搭建步骤却没写构建选项，等等。要知道，流程文档是写给不懂这些的人看的，所以应该将命令行要输入的内容全部网罗进去。

NOTE

能自动化的地方不能太吝啬成本，应当尽量自动化，从而降低搭建环境和编辑文档的成本。

在一些环境搭建流程尚未优化的项目中，单是给一个开发者搭建环境就可能花费超过一周的时间。这种情况下，每当遇到实现或测试阶段都会消耗大量的人力资源。软件开发项目中的许多机制都可以自动化，其中与搭建环境相关的自动化最好在项目起步时就准备好。

本书将在第 9 章和第 11 章中介绍自动化搭建环境的相关内容。

7.4.6　面向客户

面向客户的文档包括指导如何使用成品程序的学习手册，以及总结了日常操作流程的使用指南等。

当然，前面讲到的设计、开发、搭建环境等的文档一般也会交付给客户，但除了客户想自己修改程序之外，这些文档的内容都太过晦涩，而且客户无法对内容加以干涉。与此相对，使用手册是客户日常会用到的东西，而且客户在给这类文档的内容提要求时更清楚自己想要什么。是否需要面向客户的文档，或者文档中该有哪些内容，这都需要与客户认真探讨系统的使用情境之后再决定。如果定不下来，那么很可能是客户自己对系统没有一个明确的设想。这种情况下，客户可能在收到成品后或开始使用后才发现“这跟我想要的不一样”。所以为了防止出

现这类问题，我们必须与客户认真探讨，共享成品在开始运营后的情境，编写出所需的文档。