浅谈三大文档——需求、概要及详细

        当今，电脑已经走进了千家万户。而用360清理电脑，好像已经是每家每户经常干的事情。而我的一个远亲更为夸张，家里电脑上装满了360的套装。从浏览器到安全卫士再到杀毒软件。清理电脑清理的频繁极了，而且人家还非常关注360软件的更新，虽然他不知道是怎么回事儿，软件一有更新，就更上瘾似的去更新。

       下面我们想一个问题：为什么360能够通过不断的升级程序，达到程序的更新，而有的程序一有新的业务，就非得推倒重来呢？

       当然，初期软件的架构非常重要了。然而无论在软件设计之初，还是在软件的使用过程中，维护过程中，项目经理级别的人物交流等等，等等都离不开的，就是文档。

       说到文档，就必须得说需求、概要、详细三大文档。俗话说：万事开头难，这需求分析文档，就是该系统的头儿，它主要解决“做什么”的问题。需求分析时，系统分析员和软件工程师对客户的需求进行充分理解，然后把业务需求理解整理成文档。该文档便供架构师对该系统进行架构，包括后续的画UML图，编写概要设计文档和详细设计文档。

       个人认为，需求分析文档中可以有用例描述。用例描述，是用户与开发人员之间最好的语言，一般情况下，开发人员很难向听出来用户想要什么系统，而用户用自己的语言描述半天也表述不清自己要的是啥。而用例图能够使他们两者达成共识。

需求分析里面，还应该放置用户特点。俗话说：知己知彼，百战百胜。只有知道了用户的特点，才能对症下药，制定出符合他们的需求系统。

       当然需求里面也需要放一些其他的东西，比如关于性能描述，非功能性要求等等，这里不多少说，大家可以去百科里面查。下面说概要。

       那么，什么是概要设计文档，写完之后又要给谁看呢？

       个人认为，概要设计文档的编写就是要根据需求文档的要求，把系统具体化。将系统的功能进行模块划分，建立模块的层次结构调用关系、确定模块之间的接口和人机界面等等。

        那么概要设计文档完成后要给谁看呢？经过昨天激励的讨论，大家一定都知道了。首先，概要设计首先要给项目经理级别的人看的，他通过该文档能够了解该系统的全局以及该系统的特色和亮点。然后，概要设计也可以拿给用户看，用户经过简单的培训，大体上读懂文档应该没有问题，他们能够通过该文档了解到这的系统是不是他们所需要的系统；再然后，概要设计还可以起到唬人的作用。比如公司之间外包项目，可以拿概要设计文档对自己项目的两点和难点吹嘘一番，给人眼前以震惊的感觉。

       我们知道了概要设计文档要给谁看，那我们的概要设计要包含哪些内容呢？

       概要设计文档需要有该系统的功能介绍，但是不是功能的具体实现。当然，我们可以在里面放用例图。我们可以将我们建模的用例图放到概要设计里面，使参看该文档的人能够对系统的功能一目了然。

       另外，我们更可以把系统的主要功能界面放在该文档中，阅读者多图的吸收能力远远大于文字，简单的几幅功能图片，能够将你系统的主要功能概述出来。

       此外，我们也可以将数据库的框架设计、表设计以及系统的整体架构体（也就是包图），放在概要设计里面。目的还是一样，让用户能够从全局了解该系统。

        同时，我们也可以将我们的编程规范统一在概要设计文档中。

       个人认为，概要设计就好像人的脸一样，它就是系统的脸。通过这张脸，我们能够看到这个系统到底漂亮不漂亮，到底值多少钱，到底有没有面子，能不能唬人。

        有了概要设计，下面我们来看详细设计。

        详细设计文档一定要细致。因为它主要是给编程开发人员看的，大家要严格根据详细设计文档来编写代码，所以该文档的准确性一定要高，可以说该文档出问题，那么系统就一定会有问题。

        详细设计文档中，要包含各个层次之间的接口。比如我写UI层的代码，那么我就必须知道BLL有哪些类，有哪些方法、及其它的参数，返回值等。那么这些就都必须在详细设计文档中有详细的中文说明、英文名称。

        这是接口，那么详细设计中还需要放写什么呢？我们还可以将时序图放在里面。我都知道，时序图是对指定功能的具体实现，将该系统的主要功能的时序图放在详细设计文档中，使开发人员对层与层之间的调用关系，方法名、参数、返回值等更加了解。

        另外，系统的其他方面的具体细节，也应该在详细设计文档中声明。比如系统的精度问题、程序必要的功能、性能的描述等。

        概要设计文档给系统分了模块，而详细设计就要把这各个模块逐步细化，直到开发人员能够较轻松的看懂为止。