为啥我写不出文档

方法学 设计 文档

当有人跟你说 “我们整理一个文档” 的时候,有没有考虑过这文档是不是没法做? 就像收到需求时可以说没法完成一样,文档也不是总是可以写出来的。 下次不想写文档时可以把这篇文章丢给他,也许这是本文最大的意义。

可能因为说话是人类的天赋,从未有人怀疑过写不出文档的可能性。 这大概就是很多文档就像废话一样没用的原因吧。 那下面 Harttle 就开始列举写好文档各种客观条件,并突出其客观性和无法抗拒性。

开发方法不对

在当前所处的阶段和时机,写这篇文档的想法本身就有问题。

我们从开发方法学谈起,Harttle 见过的多数开发实践都不属于任何传统的开发方法。 如果硬要归类,可以称为勉强的敏捷开发,或者残缺的极限编程。 勉强是因为往往并不符合某些原则,比如频繁交付(在很多现实场景中确实没法及时发布给客户使用)、 持续关注设计(有方案评审已经难得,谁会在演化过程中继续关心设计,KPI 是你的设计吗?); 残缺是因为往往缺少必要的价值判断,比如保持信任(见惯了烂项目,根本不假设文档是最新的)、 频繁反馈(信任缺失导致不得已才反馈,有办法就利用它的漏洞)、 维持简单性(满足需求第一、稳定性第二,简单性一边去)。

综上,开发方法就有问题文档自然是乱七八糟。 比如给从未设计过的项目补设计文档,给测试都经常挂的项目写持续集成文档, 给先实现后设计的项目写用例文档等等。举个例子:

项目已经上线了,Boss B 来找 Programmer P 要设计文档。 P 已经看不懂自己的代码了,于是按照对这个项目的理解试图还原一份设计文档。 P 写完之后发现实现时完全不是这样设计的啊,难道要扭曲设计文档到既有实现吗? 设计文档中要不要提那些 Trick 呢?好像按照文档的设计不需要 Trick 了。

不要不要,设计文档反正没人知道。这就是编写时机不正确,导致文档含糊其辞。

开发方法没有正确的只有合适的。但实际选择时,往往会忽略一些非功能需求。比如性能、可维护性、可测试性、文档等等。简言之,设计开发流程时根本没考虑设计和文档。

需求不清晰

需求不清晰,无法完整地描述需求。

还记得 需求分析 阶段在开发方法中的目的吗? 分析客户的需要和条件,对自然语言描述的业务需求文档进行分析, 通过用例图、软件原型等手段找出其中矛盾的部分, 产出完整的功能分析文档,并最终由概要设计阶段来确认。

如果缺少必要的需求分析,上述 矛盾的部分 不仅会扭曲设计和实现, 更影响文档的编写。这部分需求有很多种具体的表现:

  • 真的是矛盾。例如要提供一个离线模式,但同时又要能够发送消息。无法实现,要求更改需求。
  • 奇怪的需求。例如你在开发一个下拉菜单,被要求领导的名字要在前面。其他机制实现,跟下拉菜单无关。

现在到了写文档的时候。同样地 Boss B 还是来找 Programmer P,不过这次要的是接口文档。 这时 P 刚开发完上述列表中的需求,然后便开始写文档:

  • 离线模式。现在用户处于离线模式了。但你非要发消息,可以传这样一个魔法参数。但有些情况下会发不出去,但这不是 bug,因为处于离线模式嘛。
  • 下拉菜单。本组件可以产生一个字符串列表的下拉菜单,注意当你的字符串匹配到我的领导列表时,顺序会变。要更新领导列表,可以拷贝一份自己改。

这就是需求分析不清导致文档难以理解。

设计不完整

*设计阶段** 的目标是给出满足用例和 UI 的具体设计,包括时序图、类图等描述系统结构和行为的文档。 即使能够成功地实现和发布,设计阶段的缺失或失败也会导致文档没法写。

例如需求方 R1 要一个用户管理,可以添加、修改、查询,通过 HTTP 接口进行操作。 经过简单的拍脑袋,P 同学很快就写完了代码并上线。 不幸的是另一个需求方 R2 也需要用户管理,Boss 说我们有啊,于是 P 同学继续写接口文档。

用户管理文档:该 API 支持 CRUD,通过 POST 来创建;GET 来查询;PUT 来更新; DELETE 什么都不发生,将来可能会增加删除接口,注意做好兼容。 这个缺失的接口设计造成的影响不仅仅是文档不完整,以及后续变更很可能会让文档与实现不一致, 更容易引发误用事故。作为 R2 也自然会喷这个文档垃圾。

这就是设计不完整导致文档不可依赖。

本文中描述的需求分析、设计阶段等概念只在特定的开发方法上才存在。 但在其他开发方法中一定存在对应的工作,可能是 F2F沟通、每天站会、设计草图、会议纪要等。

转载请注明来源: https://harttle.land/2018/03/19/a-document-i-wont-give.html 欢迎对文中引用进行考证,欢迎指出任何不准确和模糊之处。可以在下面评论区评论,也可以邮件至 harttle@harttle.com

🔝