交付文档写得糙,后续会以三种方式反噬:客户天天问、你免费当客服、项目无法结项。
写得过多也不划算,时间成本高,客户未必看。合格的交付文档有一个可衡量的标准。
合格文档要能回答哪几个问题?
五个。这是什么、怎么装、怎么用、出问题怎么办、怎么改。
五个问题对应五类内容:概述、部署、使用、排障、扩展。
五类里,排障和扩展最容易被省略,也最容易被追问。
概述该写什么?
三段。这个系统解决什么问题、由哪几部分组成、有哪些限制。
限制这一段最重要。写清不支持什么,能避免大量误用和无效咨询。
部署该写什么?
四个部分。环境要求、步骤、验证、回滚。
环境要求写清操作系统、依赖版本、资源需求。版本要写具体,不写最新版。
步骤要能照着做,每一步有命令和预期输出。
验证写清怎么确认部署成功,用具体的检查项。
回滚写清出问题怎么退回上一状态。这一段是保险。
使用该写什么?
按场景写,不按功能写。
每个场景包含:什么时候用、怎么操作、结果是什么样、常见错误怎么处理。
场景要覆盖高频路径和关键边界。不需要覆盖所有功能组合。
排障该写什么?
按症状组织,不按模块组织。
每个症状包含:表现、可能原因、排查步骤、解决办法。
症状描述要具体。写系统报错,不如写页面显示某某错误码。
扩展该写什么?
三个部分。代码结构说明、扩展点位置、扩展示例。
代码结构说明不用详细到函数级,讲清模块划分和数据流即可。
扩展点要标出改哪里,以及改动的注意事项。
怎么判断文档合格?
三个测试。第一个测试:一个没参与项目的人,能不能照着文档部署成功。第二个测试:客户团队能不能不看文档直接问出已经被文档回答的问题。第三个测试:出现常见故障时,客户能不能自己按文档排查。
第一个测试是硬指标。过不了,文档就不合格。
文档该用什么形式?
三种形式配合。Markdown 放在代码仓库,方便版本管理。PDF 或在线文档给客户,方便阅读。速查卡贴在工位,覆盖最高频的操作。
三种形式内容一致,来源单一。
交付时怎么用文档?
做一次文档走查。让客户团队按文档操作一遍,记录卡住的地方。卡住的地方就是文档要改的地方。
这个动作能把文档从写完变成可用。
实测数据说明了什么?
做过文档走查的项目,交付后一个月的咨询量明显低于没做的项目。差异主要来自排障部分。
有哪些风险与合规要点?
文档里不要写客户的敏感信息。示例数据要脱敏。涉及第三方服务的配置要注明来源。
结论?
合格的标准不是写得多全,是能让人独立用起来。
按五个问题组织内容,做一次走查,文档就够用了。追求完美文档是浪费,追求可用文档是投资。
去论坛讨论
前往 ziyuanagi.com 论坛 参与讨论