写规范文档,最难的是定名词,先把这个“术语表”统一了

写文档的朋友都有这种经历。你花三天写了一份需求说明，发给团队。大家看完都沉默了。不是没看懂，是大家对同一个词的理解不一样。

你说“用户”，你指的是网站访客。测试说“用户”，她指的是注册会员。开发说“用户”，他眼里只有数据库里的那行记录。三个人开会吵了半小时，最后发现说的根本不是一回事。

写规范文档最难的，不是语法不是排版，是定名词。名词定不好，后面的所有内容都是白搭。你写“前端用户提交表单”，开发看到这句，他琢磨的是“前端是指浏览器端还是手机端”。测试看到“提交表单”，她想知道“提交成功之后跳转到哪个页面”。产品经理看到“用户”，他问你“用户登录了才叫用户还是没登录也能提交”。

我以前写文档不重视这件事。我觉得“用户”这个词很明确啊。直到有一天，一个新人问我“老张你说的这个用户，到底是有权限的还是没有权限的”。我愣了。我回看自己的文档，发现“用户”这个词出现了几十次，每次表达的意思都不一样。

那之后我学乖了。每次动笔写正文之前，先搞一个“术语表”。就是把文档里会用到的关键词，一个一个列出来，给它们下死定义。比如“用户”这个词，我规定好：凡是没有登录的人，叫“访客”。凡是登录了但没开通会员的人，叫“注册用户”。凡是开通了会员的人，叫“付费会员”。这三个词在整份文档里，不能混用。

这样做了之后，团队沟通效率明显上来了。开发不会问“这里用户到底指谁”。测试写用例也不会凭感觉。产品经理看文档也能一口气看到底。大家不用反复确认“你说的那个东西是不是我想的那个东西”。

定名词这件事看着简单，做起来特别考验功底。因为你要把模糊的东西变得精确。比如“系统”。这个词在文档里特别常见。“系统”到底指什么。是软件本身，还是包含硬件。是后台管理界面，还是前台展示页面。你不说清楚，开发就以为是全栈，测试就以为只测前端，运营就以为系统会自动帮她完成所有操作。

我见过最让人头疼的文档，就是名词前后不一致的文档。前面还叫“订单管理”，后面突然变成“交易记录”。前面说“数据导出”，后面说“报表下载”。读者越看越糊涂，到底这两个东西是不是同一个功能。如果是一个功能，为什么要用两个名字。

所以我给自己定了一个规矩。文档里一个概念只能对应一个词，一个词只能对应一个概念。不搞花活。“订单”就是“订单”，不到万不得已，不要搞“工单”“单证”“交易”这些同义词。除非你真的想表达不同东西。

还有一点要提醒大家。定名词不能只靠你自己拍脑袋。你得找团队一起商量着定。你一个人定下来的“访客”，开发可能习惯叫“游客”。你坚持用“付费会员”，销售觉得“VIP客户”更好听。不统一的话，你写文档是一种叫法，开发写代码用另一种叫法，测试写用例又是一种叫法。最后文档和产品对不上，谁都不认账。

最好的办法，是在项目启动的时候就把术语表定下来。拉上产品、开发、测试、运营，坐在一起。一页纸，把所有关键名词全部列出来。大家现场讨论，现场拍板。定下来的东西打印出来贴在墙上。谁都不能随便改。谁要改，重新开会投票。

这个习惯看起来很麻烦。但等你真正开始写正文的时候，你会发现顺畅极了。你不用在每一段都反复解释“这里的用户是指已登录未付费的”。你只需要在文档开头写一句“本规范中‘用户’一律指代已登录未付费的账户”。后面所有地方直接用“用户”两个字就行。

很多人写文档写不好，不是文笔不行，是名词体系没搭好。名词定稳了，整篇文档就不容易跑偏。就像盖房子，地基打牢了，墙才不会歪。

今天就写到这里。如果你也遇到过因为一个词语跟同事争论半天的情况，不妨试试先定术语表。真的有效。