如何写软件的需求和设计文档

青旅半醒 2022-05-25 13:51 261阅读 0赞

编程快20年，写了一些的文档。

之前也一直在思考如何写文档，这个过程中，有几次提升。

一次是在华为，学习如何写设计文档。

另外就是写需求文档，这次的项目，以前需求写得也比较多，但都是有足够的思间来慢慢写，这次时间比较紧张，所以，思考如何写作需求。

==============================

开始之前，

我们还是先回下头，想想到底什么是软件。什么是硬件。

这是因为，许多公司，特别是中国现阶段，实际上大多数公司是硬件公司，然后去开发软件，然后用硬件的思维去写软件文档，各方都很别扭。

有的人，以为，用代码写出来的，就是软件，这有些片面。比如CPU也是代码写出来的，但它似乎是很硬的。

所以，有人说华为是家软件公司，理由是大家都在写代码，这有点让人哭笑不得。

===========================

这里，我来斗胆定义一下吧：与人打交道的，特别是人机界面相关的，就是软件。

另外，是状态相关的。

比如，windows的win32API，算不算软件？以前我以为是，现在我觉得不是，当然，也不能算是纯硬件，属于一种中间态吧，因为它不满足状态相关这件事。显然，我们人类是有记忆的，对吧。

列一下，软件两个必要条件：

1. 与人打交道，人机界面相关。

2. 状态相关的。

还有一个最好满足的条件：

3. 用来赢利的，不是给自己公司人使用的。或是管理自己的硬件设备产品的。

比如，华为的网管软件，其实不能算是软件。

================================

我们开始吧。

先从需求开始。

如上所述，需求的要点是从人开始。

也就是从使用者的角度来看。而不是从实现的角度来看。

设计文档，则是在需求明确的前提下，从设计的角度，来描述，如何实现的。

需求文档的输入是用户的述说，输出给项目经理，项目经理，进行全面的评估，比如，查看范围是否划的明确（这是最最重要的一点），能否实现，如果能实现，公司的资源，能否支撑，质量、进度、成本目标是否能够达成？

然后下达给技术经理，进行设计。

当然，不得不吐槽，中国的软件业乱七八糟，怎么干得都有，往往是项目经理，自己组织立项，自己组织写需求。

最后项目经理，需求经理，技术经理，还有产品经理各人一嘴毛，谁都想跨过自己的边界。唉，不扯这些了。

最后所有的人，都可以指责项目经理，唉，不做事不犯错，实际是因为边界。所以，下辈子，不当项目经理，要当给自己的公司当。

需求实际上，的确不应当由项目经理定，虽然他要参与需求的制订，但他不是写需求的人，他只是负责执行。

技术经理，负责实现的图纸。

产品经理，负责验收结果，也就是代表业主方。或者需求方。算是一个只在关键点有话语权的财主，可实际上，地主来干涉长工干活的事情，在中国很普遍，我说过无数次了：对于中国人来说，边界是个大难题，无数人，到死也没搞清楚边界，谁不想把别人的老婆变成自己的呢？当然，真变成了，也肯定是悲剧了。

吐槽也有好的一面，如果你真看明白上面的文字，你可能了解你的公司的问题在哪里。

有人总是在纯想技术，项目失败，实际上多数时候，70%以上吧，来自于组织的问题。

=======================================

如何写需求

1. 准备一下：写写前因后果，给系统起个名字，然后试图划清边界和规模。这个很难，但必须要做。

2. 分清角色。

3. 站在每个角色的视角，提出，有哪些需求。这一点，回顾一下上面的描述，就出来了，要站在人的角度，如果与人无关，就没有需求，交给实现方就可以了。比如，用户的需求，是把数据从A地传到B地，我们可以选装硬盘里用车拉过去，还是用TCP/IP协议传过去，用户是不在意的，这种情况，比如，“首先雇辆车，然后硬盘装车，诸如此类的”，就不要写了，这虽然也是与人打交道，但这人不是你的用户；如果把TCP/IP协议栈当作人，自然更离题了。

4. 然后是细化。每个动作的详细的描述，包括：输入（前置状态或允许条件等），输出，状态的改变

=========================

设计文档，

相对就更好写一些。

主要是层层分解。

每一层都要先描述出：

1. 自己在上一层的位置

2. 自己与同层的模块或系统或子系统之半的关联关系，这时，这些接口，已在上一层的接口描述中定义，只需要提一下即可。同层的模块间的流程，也不要写，因为在上层已写过。

3. 自己的内部构成，也就是模块分解。每模块功能简要描述。

4. 内部模块间关联关系和接口描述。

5. 子系统的主要流程，主要说明每个流程，各内部子模块之间的协作，主要是指信息流动，和各子系统的状态变化。也就是输入，动作，输出。

*今天过来看，意外的是，还偶尔有同仁查看了本贴，这里稍稍补充一下（关于设计文档）：*

（1）相信7原则。我们大脑是7维的。所以，在同层，模块尽可能不要超过7个。如果超过，要重新平衡。当前，在设计文档的前期，大家会想得很全面，很可能模块超多。但最后阶段，每个模块都出来后，项目经理，一定要参与取舍。主要是舍。你的部下，大多把能想到的都想到了。但不要超过7个。有的模块可以是上层另一个单元的，有的，这次就不能实现。因为安，投，进，质，合，信，组（安全，成本，进度，质量，合同，信息，组织）。这些都 是项目经理的责任（组织不是），而设计和实现者不在乎这些。这点很难。但很重要。系统工程是很残酷和违背人性的，很客观。没办法。

（2）关于分层，最好不要向下超过三层。L0,L1,L2，类似总体设计，概要，详细。不要再向下细了。再向下的，让各个小组自己编写即可。作为一个个专题，项目内部控制，可以请你的PM帮你在日后走相对简单的流程入库 。不必体面在全局性文档中。因为那样，文档太长没法看了。而且很难过审。那些官老爷，你写得越多，越不好过，你的项目开工日期 就可能一直拖下去。恰到好处，宁少毋多。但一定要下探到小组级别(特别是小组的接口和接口人的位置)。以免日后项目失控。