软件开发文档之概述

        文档一直写得不好，上次收费系统验收更是看出如此，这与项目开发经验不足有关，也和自己懒得总结的惰性有关；所以想着结合以前的经验，较为系统的总结一下系统开发文档。

        分述各个文档之前，咱们需要先看看涉及到文档书写的其它问题，以便从侧面和宏观了解文档。先了解一下软件开发设计到的人员，解决文档中的“谁”的问题。

        人员组成

人员	作用
用户	软件开发的参与者和最终使用者，负责提供需求和指正开发中的偏差。
项目组长	负责协调开发人员之间、用户之间、开发人员和用户之间的关系，领导整个项目的开发。
系统分析员	负责用户和开发人员之间的沟通，可以看做是系统开发的核心人物；最主要的工作是把客户所表达的需求转换为开发所用的需求，在以后的开发中修正需求偏差，并在测试阶段与用户共同制定测试标准、测试计划和准备数据。
硬件网络设计员	根据开发需求提出对硬件网络的基本要求并制定硬件网络配置方案；负责该方案的实施。
数据库管理员	根据开发的数据需求数据库的设计、定义和存储，负责在系统运行中监督、控制和维护数据库。
系统设计员	负责对实现系统的硬件、软件环境的总体设计、模块设计和模块间接口的设计工作。
程序员	实现方案中的各项功能；用户使用培训；系统测试和试运行

         分类是死的，项目是活的，以上只是分析人员组成，真正情况下会根据系统的大小和类型，决定是否进行角色合并，例如较小项目，组长也可以参与到代码、测试等工作中。

        关于文档，各位可能和我有同样的感觉，不知道文档是什么、为什么写、谁写的、写什么、写给谁这几个问题，此系列博客将从这几个方面切入，总结一下文档的书写。

        是什么？

        文档是系统开发建设的主线，贯穿于系统开发的整个过程，开发的各个层次和阶段都需要相应文档，起到开发各个阶段的记录和确认作用。对文档有一下几个原则：

标准规范化	系统开发前制定文档编写标准，在此标准下书写所有文档
一致性	各个文档之间要保持一致性，修改某个文档相关联文档也要修改
可追踪性	系统开发中的修改，也要反映到文档上面，保持文档与开发的版本对应
管理制度化	管理文档也要制度化，包括文档标准、修改文档等的条件、开发人员的责任和任务

        再通俗点，文档就是用来记录开发过程中的内容、问题、解决方案、结论的，这个是文档的前提。

        为什么写？

        不知道文档为什么而来，还写它干嘛？知道为什么要写文档，有助于理解文档的立足点和方向。

        为什么写文档？咱们举几个例子：

        1、开发前公司派你去看看用户需要什么功能，你回来怎么跟公司交代？

        2、你说你知道了用户需要什么样的功能，怎么表现出来？

        3、用户要和公司签合同以什么为准？

        4、你把几个程序员叫到一起说：咱们要开发系统啦，然后一个一个叮嘱怎么做？

        5、软件初步完成后可能有各种各样的错误，靠拍脑门决定输入什么来测试？

        6、用户不了解软件怎么使用，难道手把手一个一个的教？

        我认为这些矛盾就是写文档的原因：你把用户需要的功能整理起来给组长说，这就是他们想要的功能；把用户要求的和软件要达到的目标整理起来，交给公证说：这是我公司和用户的约定；把每个程序员需要做的整理出来，告诉他：你做这些就行；把你知道怎么使用整理出来，交给用户，还可以复制给其用户学习使用……

        没有文档或是文档写的不明了，就像刚开始合作开发收费系统，一会问这个函数是干什么用的？一会问这个函数需要什么参数、参数什么类型、怎么命名……在这种情况下，分工的意义近乎为0，因为把时间都花在了交流上面。

       上述需要整理的，我们就可以称之为软件开发中的文档，有了文档，大家要做什么？做成什么样？都有了标准，任务分工更为明确任，总之就是：“口说无凭，立字为证”，这个是文档的动力。

        谁写的？

        同样是需求规格说明书，用户写出来的（如果可以）和开发人员写出来的肯定相差巨大，所以学写文档也得知道这个文档是由谁写的。知道哪个文档由谁写，才能从这个角色的角度出发，写出立场和角度合适的文档，这个是文档的起点。

        写给谁？

       试想面向用户的文档，满篇的类、架构、数据、设计模式，用户肯定看不下去。知道要写给谁，才知道用什么语言、什么方式去写文档，这个是文档的方向。

        写什么？

       每个文档都有指定的预期阅读人员，先不说具体内容是什么，就达到文档可理解、思路清晰、简单明了的目的，也是一个不小的挑战。再说内容，文档的内容取决于上述几个书写重点，再根据具体的开发系统补充细节即可，每个文档的侧重点也不同，后面的博客再一一详写。

        上述的几个要点都是重点铺垫，这个是文档的灵魂。

        软件开发文档概述先到这里，接下来的博客会详细介绍常见文档的书写及注意事项，敬请期待。