【实践案例】文档工程师帮助业务避坑案例

众所周知，参数类相关文档是技术性较强的文档，参数如何写才能体现公司产品的优势又巧妙的避免技术实现的不足呢？

做为某大公司软件服务的文档顾问，我接到上司的需求，要求帮他新增一个性能实现的前提，具体内容是：

原文：在运营商通道稳定的情况下，国内短信的可达率为99%，最大时延15秒，平均到达时间为7-8秒。

领导要求，新增电话号码有效的前提，另需要对有效号码进行解释：

第一轮修改后：在运营商通道稳定且号码有效的情况下，国内短信的可达率为99%，最大时延15秒，平均到达时间为7-8秒。

备注：有效号码是指XXXX

背景的领导对逻辑性要求极高，要求我参阅阿里云的文档新增对可达率的解释。本能地觉得可达率这种显而易见的概念没必要解释，且经再次查阅竞品文档，果然发现竞品没有解释可达率，另外，还有一点重要发现，其它竞品没有写最大时延和平均到达时间。

于是我向上司建议：1.为了保证文档简洁性，配套文档不用解释可达率这种显而易见的概念；2.避免自爆弱点：删除最大时延15秒。3，避免竞品调查，提炼出较好服务性能表现，改成秒级可达（十秒以内，都算秒级）。4.观察到该文档下一个主题只用了80字，这个主题用了150字。需要进一步提炼，保留精华信息。

第二轮修改后：在运营商通道稳定且号码有效的情况下，国内短信的可达率为99%，秒级可达。

备注：有效号码是指XXXX【缩略版】

总结以上案例，笔杆子在撰写参数相关的技术文档要做到三点：

1.对业务相关的关键参数有深刻的理解，这可以帮助我们在写作过程中，抓住凸显业界领先，也可以让我们避免对客户输出不太理想的参数。横向比较竞品在每个模块上的表现，可以我们在面对突围时更有底气，必要时要进行主题研究。

2.信息简洁可读性可以帮助用户提升阅读体验，降低文档的信噪比。与核心数据不相干的简单概念可以不写，横向比较类似信息的体量，做到横向一致性。

3.技术文档不仅带有技术性，也带有营销性，保持商业思维，让产品和服务更有吸引力。