toB 软件由于专业性较高，很难像 toC 软件那样上手就玩。于是软件使用文档写得好不好，相对来说显得比较重要。我们经常可以看到类似的抱怨：“这文档写的，完全看不懂”。
抱怨毕竟是主观的，具体到单个读者，他看不看得懂文档，可能最大的影响因素是他自身的技术能力，而不是文档质量。但有没有客观的评价方式呢？
有！
在上次介绍的 write the docs 大会上，有外国同仁分享了自己的开源项目，叫 lexi。每次文档提交 git 的时候，用 lexi 评估一下修改前后，文档的可读性指标是否明显下降，下降就不给提交。
不过很可惜，lexi 项目使用的这些评价指标，都是专门针对英文文档的。指标计算中使用的一些因子，比如单词长度什么的，对中文汉字来说，压根不存在任何意义。
我花了两天时间，在知网上广泛搜索，发现中文文本可读性评估，虽然还没有广泛公认的指标，但也已经积累了一些研究成果。于是用 claude AI 帮忙（我只负责找资料写 prompt，代码都是 claude 生成和修改的），快速实现了一个版本，发布到 PyPI 上，供大家把玩：
https://pypi.org/project/readability-cn/
安装完成后，自带了一个简易的命令行工具，可以做快速的评分：
不过大家可能发现了：上面截图中，评分似乎都很低啊？
确实如此。因为当前中文可读性的研究，主要出自中小学语文和对外汉语教育领域，在做线性回归拟合的时候，使用的数据样本都是语文教材文章，对词汇难易程度的判断标准差不多是 HSK 汉语考试三级的水平——显然，这个标准评估公众号小作文可以，但评估 IT 使用手册是不合适的——但我目前没找到 IT 领域通用词汇列表。
每个指标的计算公式和因子标准，都在 python 的函数注释中写明了，有兴趣的读者可以直接阅读：https://github.com/chenryn/python-readability-cn 。也欢迎大家在 github issue 上对“IT 领域通用词汇”这个问题，提出自己的建议。
当然，绝对值无法参考，变化值却有意义。我们依然可以从文档变化前后的评分变化中，来客观地判断本次变更是否有明显的问题。像上图这种变化不大的，基本也可以接受。
