夜雨聆风学习资料网

ARTICLE · 1382332

技术文档没人看怎么改

技术文档没人看怎么改

▍一键复制全文 · 长按本文下方正文可复制,方法可直接照做

图1 · 扁平几何插画 · 本文自制

文档写了一大堆,新人还是天天在群里问同样的问题,老成员也懒得翻。很多人第一反应是文档写得不够多。结论恰恰相反:文档没人看,多半不是篇幅不够,而是组织方式不对——按代码结构堆、步骤不能照抄、更新跟不上,三条占了九成。

01 背景与对照:没人看的原因

技术文档有个尴尬的现实:写的人觉得已经写全了,用的人却根本找不到、看不下去。于是文档越堆越多,问题却反复被问。根源往往不在字数,而在它是不是站在用的人这边组织内容。

没人看的原因归纳为四类:按模块堆,完全照着代码目录分章节,用的人根本不知道该看哪一章;不可复制,步骤只写成描述,读者得自己拼命令;内容过时,文档和现网对不上,看一次错一次,久而久之没人再信;入口难找,散落在各处搜不到。

图2 · Unsplash

对照看:按代码结构组织的文档,是站在写的人一侧的目录;按使用任务组织的文档,是站在用的人一侧的索引。读者带着一个具体问题来,他要的是直接告诉他从哪步到哪步,而不是先理解你的系统分成几个模块。

还要接受一个事实:文档的价值由用的人决定,不由写的人决定。写得再漂亮,解决不了一个具体问题,就是无效文档。所以改造的起点不是扩写,而是去看大家到底在反复问什么。下面矩阵列出要改的几个维度。

图3 · 信息图·矩阵对照 · 本文绘制(维度为通用做法)

02 机制与要点:四个改法

第一个改法是按任务组织。别再按模块分章,而是按使用者要完成的任务来分篇:怎么配环境、怎么排查某类故障、怎么走一次发布。一个问题一篇,标题就写成问题的样子。读者搜到标题,就知道是不是自己要找的。

第二个改法是给可复制的步骤。需要执行命令的地方,直接给出完整、能照抄的命令,注明在哪个目录、用什么权限执行。只写配置一下某个参数这种描述,等于没写——读者还得自己去猜具体命令。可复制是文档能否被用起来的分水岭。

第三个改法是让文档随代码更新。把文档和它描述的代码放在一起维护,改代码时顺手改文档。文档里标注最近核对日期,超过一定时间没人核对的标记为待复核。文档过时的危害比没有文档更大,因为它会误导人。

图4 · 信息图·流程节点 · 本文绘制(文档改造流程)

第四个改法是统一入口。把有效文档收拢到一个索引页,按任务分类列出链接,让人不用到处翻。四个改法合起来,文档就从一堆给别人看的资料,变成一套给任务用的工具。判断标准始终是一个:能不能让人少问一个问题。

03 实操清单:条目模板与自查

自查建议固定四项:按任务组织、关键步骤可复制、标注更新时间、有统一入口。四项缺一,文档就容易出现找不到、步骤无法执行、内容过时这类老问题。这张清单可以直接用于一次文档体检。

图5 · 信息图·双栏清单 · 本文绘制

每篇文档建议固定六个字段:适用场景、前置条件、操作步骤、预期结果、常见问题、更新时间。适用场景让人一眼判断是不是自己要找的;常见问题把反复被问的坑直接写进去;更新时间让读者知道内容新不新。这张表既是写作模板,也是检查清单。

改造时别想着一次性把所有文档重写完。先列出被问得最多的那批问题,逐个按模板重写,验证确实能减少提问,再扩展到其余。字段模板见下图,可直接复用。文档治理是持续的事,贵在坚持,不在一次大扫除。

图6 · 信息图·双栏清单 · 本文绘制

04 判断口径与收束

判断文档有没有改好,问一句:同一个问题,群里还被问几次?从这个月到下个月明显减少,说明文档真的解决了问题;没有变化,说明写的还不是大家要的。重复提问次数,是文档价值最实在的度量。

下面这张时间线是治理节奏示意,属于设计参考区间,按团队规模和文档数量伸缩。先看重复提问、再重写高频文档、然后补样例和入口、最后回看数据。用数据验证效果,而不是凭写完多少篇来判断成绩。

图7 · 信息图·时间线 · 本文绘制(节奏为设计参考区间)

好的技术文档不是写出来的,是用出来的。把组织方式从给人看改成给任务用,把步骤写成能照抄的样子,让内容和代码一起更新,文档才会真正成为团队的资产。少一次重复的提问,就是文档价值的一次兑现。

本文方法为通用工程实践,参数为设计参考区间而非统计值。

回首页,搜索你想要的文档

在首页搜索框输入关键词,快速定位资料

文库首页搜索指引 立即搜索

相关学习资料