字数：2055

引言

看到了一个历史项目的八股文，又联系到我们平时用于项目沟通的文档，想到很多。 焦点问题就是：写一些什么东西才能准确地反映系统，又能很好地让人看明白。此篇并没有提出解决问题的准确答案，也许这个问题一直在路上。

1 八股文

看到国家图书馆的一个门禁系统的项目，大概是09年前后开发，项目开发相关人员大概4人，需求感觉是比较简单的：

  • 采集照片，有什么用？仅仅是照片存档。采集有三个来源：一是照片采集客户端采集读者卡中的照片，二是办证机办证时的二代身份证照片、三是门禁点的采集的二代照片。

  • 验证身份，根据读者卡或身份证，查询是否存在读者卡或身份证，是否有权限访问，无则信息报警。

  • 流量发布，进场加1，退场减1。

  • 统计分析，比如根据时段、馆点，结合进场次数、年龄段、卡证其它过滤条件来查询数据，并支持导出。

从需求看，真的是比较简单的几个接口的事，而这个系统最终做成什么样？大概看了一下，测试用例就拆成有300个左右。项目文档给人的感觉也是大气磅礴：

  • 架构说明书大赞SOA的优点。

  • 系统需求分析说明书63页18000字左右、接口规范说明书34页、详细接口说明书151页38500字。有点按瀑布模型来开发系统的， 关键是这几篇文档里的，大量的重复和堆砌内容，让人看不到重点，特别是后两篇，完全是迎合软件工程的概念。

  • 测试用例文档58页32000字、系统测试报告15页6500字、性能测试27页2000字。仅性能测试报告让人有眼前一亮的感觉，其它内容及其组织形式，让读者很痛苦。

综合来看就是，感觉这些文档不是给人看的：-（。不过不管是正面的还是反面的，总会给人以启示，比如为什么需要这些文档，这些文档达到了 价值的初衷了吗？还能怎么写，比如哪些地方可以人性化、实效一点，等等。

2 现在的项目文档

现在项目的文档，其实也是有问题的。先列一下，都有一些什么文档吧：

  • 在项目启动阶段，会出几版PRD产品需求文档，把需求、基本的功能、业务流程定义一下

  • 在开发的前期，出几版HLD概要设计说明书，把系统结构、界面、用技术来转换一下之前的业务流程，然后出一些UML图

  • 详细设计文档，缺。

  • 开发过程中，会零星的补充一些流程图，即便是很细节的部分，比如微信登录（包括免登录）与手机登录的统一流程。 有站在数据角度的办证业务流程，这个就涉及到小程序表单、页面，后台接口（或第三方），底层数据库三者之间的关联处理或依赖的流程表述图。

  • 测试部另外划分管理的，测试用例和报告应该有一些。

3 文档做什么用

这章来综合一下，我们为什么写这些文档。显然，写文档不是为了好玩，也不是为了好看，是实际的需要。 下面是我个人理解，我觉得这些时候都需要文档，也给这种文档定义了一个名称，当然这种名称与传统的说法是有出入的：

  • 1 任何讨论需要定义一个讨论范围，比方在讨论项目需求，是有范围圈的，也可以理解成社会背景、商业分析、实用场景等？这个文档是立项文档？

    此类文档读者是：高管、项目管理、产品、设计、开发、测试、运维

  • 2 明确一个讨论结果，比方项目需求讨论后，肯定要形成结果，比如站在自然角度描述业务场景，比如我要办证，我要登录，这里面是有自然角色的，就是把这个事情说清楚。 附加的情况也要说明，比如办证需要信用达标、实人认证等。这个文档是需求文档？

    此类文档读者是：高管、项目管理、产品、设计、开发、测试、运维

  • 3 定义比较明确的业务流程和逻辑关系，以达到满足需求，当然还包括第三方服务是什么的，这个算是一个偏解决方案的，完全是针对需求文档的。这个文档是概要设计文档？

    此类文档读者是：项目管理、产品、设计、开发、测试、运维

  • 4 定义软件界面与业务的关系，这个设计师和开发都要关注的。这个叫产品原型文档？

    此类文档读者是：项目管理、产品、设计、开发、测试、运维。这个文档特别依赖第3个文档。

  • 5 定义软件服务规格，主要就是验收产品用的，关联文档或许有测试用例文档。这个叫产品规格文档？

    此类文档读者是：项目管理、产品、开发、测试、运维。这个文档特别依赖第4个文档的，与6、7可以同步撰写，甚至在开发、测试阶段都可能补充。

  • 6 定义系统架构，以及开发是如何实现业务流程的，这个基本上是给开发工程师看的，所以涉及前端、中台、后台以及数据库。这个叫详细开发文档？

    此类文档读者是：项目管理、开发、运维

  • 7 定义系统周边信息，比如运维环境。这个叫系统运维手册？

    此类文档读者是：项目管理、开发、运维

  • 8 软件使用说明。这个叫用户手册？

    此类文档读者是：项目管理、产品

目前觉得有一些明摆着的问题：

  • 有哪些文档并不是很清晰，前文算是一个思考。

  • 确定了该有的文档，那文档内容，哪些是要讲透的，哪些是不要触碰的，即文章的边界，这块是要在实践中反复打磨的。

  • 感觉有一个永恒的缺陷，文档本来是为了促进信息传达，但是缺少立体性，讲一方面是一方面，其它方面有何体现，或有无影响别的什么方面， 难以直观和具体化。简单说就是文档有点笨，能不能有一个AI系统啊，不管是高管、产品、设计、开发、测试、运维、市场，一目了然，想站在哪个角度理解，就能出来他关心的关键问题。