技术写作的难度和同理心

想到这个话题是因为 这周 Bytebase 的新版本发布。Bytebase 是两周发一个新版本，这周正好赶上发布周，伴随发版就有更新日志，文档，社交推送等一系列的内容要发布。经过近 20 次的发版，我们也梳理出了一条完整的发布流水线，还写了一个详尽的 step-by-step 内容发布指南。

虽然流程走了很多次，也有详尽的文档，但每次总有小问题发生。比如说这次，我们发布里有一步是发布 newsletter, 要替换一下按钮的链接。

同学确实「严格」按照指示做了替换，从收到的 newsletter 点进去

然后就跳到了指示里的那篇文档，而不是预期的 changelog (￣▽￣///)

当初作者的意图显然是想让同学换成内容相对应的链接，但因为没有特意加一句说明，结果发布同学不幸上钩 (Hook) 了。

Bytebase 走的是靠输出高质量内容来吸引流量的路线，所以我自己的内容输出频率也高了不少，实践过程中，我对于技术写作也愈发敬畏。因为我们主要输出的是英语内容，所以创业初期，我觉得找一个英语专业过硬的同学来就行，结果发现太 Naive 了。语言词汇只是基础能力，往上需要整体的逻辑组织，再往上需要能和读者建立共情。而和读者的共情首先需要对事物具备敏感度，此外还要具备同理心，而培养技术写作的同理心又需要了解技术本身。这些条件加在一起就很难了，先天上需要敏感度，语感和逻辑能力，后天上还需要专业训练和技术功底。

这里说的同理心，不仅针对他人，也是针对自己，因为技术内容往往之后的消费方就是自己。写的代码，注释，指南也是为了留给几个月后的自己看的。

就像这份内容发布指南，其实这次上当的同学就是当初指南的作者，结果掉到自己挖的坑里了。