交付文档写得糙,后续会以三种方式反噬:客户天天问、你免费当客服、项目无法结项。

写得过多也不划算,时间成本高,客户未必看。合格的交付文档有一个可衡量的标准。

合格文档要能回答哪几个问题?

五个。这是什么、怎么装、怎么用、出问题怎么办、怎么改。

五个问题对应五类内容:概述、部署、使用、排障、扩展。

五类里,排障和扩展最容易被省略,也最容易被追问。

概述该写什么?

三段。这个系统解决什么问题、由哪几部分组成、有哪些限制。

限制这一段最重要。写清不支持什么,能避免大量误用和无效咨询。

部署该写什么?

四个部分。环境要求、步骤、验证、回滚。

环境要求写清操作系统、依赖版本、资源需求。版本要写具体,不写最新版。

步骤要能照着做,每一步有命令和预期输出。

验证写清怎么确认部署成功,用具体的检查项。

回滚写清出问题怎么退回上一状态。这一段是保险。

使用该写什么?

按场景写,不按功能写。

每个场景包含:什么时候用、怎么操作、结果是什么样、常见错误怎么处理。

场景要覆盖高频路径和关键边界。不需要覆盖所有功能组合。

排障该写什么?

按症状组织,不按模块组织。

每个症状包含:表现、可能原因、排查步骤、解决办法。

症状描述要具体。写系统报错,不如写页面显示某某错误码。

扩展该写什么?

三个部分。代码结构说明、扩展点位置、扩展示例。

代码结构说明不用详细到函数级,讲清模块划分和数据流即可。

扩展点要标出改哪里,以及改动的注意事项。

怎么判断文档合格?

三个测试。第一个测试:一个没参与项目的人,能不能照着文档部署成功。第二个测试:客户团队能不能不看文档直接问出已经被文档回答的问题。第三个测试:出现常见故障时,客户能不能自己按文档排查。

第一个测试是硬指标。过不了,文档就不合格。

文档该用什么形式?

三种形式配合。Markdown 放在代码仓库,方便版本管理。PDF 或在线文档给客户,方便阅读。速查卡贴在工位,覆盖最高频的操作。

三种形式内容一致,来源单一。

交付时怎么用文档?

做一次文档走查。让客户团队按文档操作一遍,记录卡住的地方。卡住的地方就是文档要改的地方。

这个动作能把文档从写完变成可用。

实测数据说明了什么?

做过文档走查的项目,交付后一个月的咨询量明显低于没做的项目。差异主要来自排障部分。

有哪些风险与合规要点?

文档里不要写客户的敏感信息。示例数据要脱敏。涉及第三方服务的配置要注明来源。

结论?

合格的标准不是写得多全,是能让人独立用起来。

按五个问题组织内容,做一次走查,文档就够用了。追求完美文档是浪费,追求可用文档是投资。

去论坛讨论

前往 ziyuanagi.com 论坛 参与讨论