如何写技术文档

[hxndg]

前言

我这两天翻了下国内的一些文档规范，发现基本都是规范格式，缺乏对写文档的通用思路，所以写一个通用的写文档思路。

写前准备

写之前要做的东西并不多，大的方面就两个：

• 规范术语：规范技术文档中用到的专业术语，中文互联网一个导致谬误丛生的原因就是各种同义词乱飞，因此很有必要再一开始就确定专业术语，约定隐喻是什么。如果中文不好表达，可以一开始就使用英文规范
• 对阅读者建模：文档最终是要给人看的，表达的方式要根据阅读者的身份变化。从我个人的角度来看，如果是给 QA/PM 看的文章，那么务必保持术语的通俗易懂，尽量使用平易的语言，同时逻辑递增要保持渐进性，不能上来就什么“hash”加密，

写作要点

编写文档的时候，注意的要点要跟随文章类型变化。但是有一些通用的方法可以使用。

• 文档编写者首先要具体地陈述问题，换言之要写出原有功能 /设计的局限性，该功能处于那一层？为什么要在本层做？有什么不足？这点写出来，就可以继续向下进行。
• 因为有不足，自然就会有客户提出需求，需要给出来客户最开始的原始需求是什么，需求经过了什么变化，为什么会有这种变化，如果是多方需求要写清楚每一方需求的变化。
• 客户的需求阐明了，下一步就是简述我们做的工作是什么，设计时考虑了哪些细节。一般我写这块的时候都是按照原有协议层次的方式来进行描写 1 每层具体提供了什么功能，可以依托现有协议地层次，或者依托功能划分地层次进行描述； 2 给出每一层我们依赖地第三方 /基础功能，并说明每层对上层提供地保证和利用的下层的依赖。层次之间的够通也需要说清楚。

写后总结

写后总结并不是总结这次写的哪里不好，而是一个总的收尾工作。同样需要考虑阅读者是谁来决定怎么写

• 阅读者是客户，那么需要给出详尽的用户使用场景及提示信息，交互信息
• 阅读者是 QA，需要给出具体的 TestConsiderration 与针对的 TroubleShooting
• 阅读者是开发，需要给出系统设计的基本逻辑，给出系统设计时的取舍。
• 无论阅读者是谁，最后都要加上 Security Consideration，即安全性考虑。

结尾碎碎念

如果觉得上面的思考过于麻烦，不如使用机械的手段，直接将文档分为：术语规范；问题描述；客户需求；详尽描述； TestConsiderration ；。。。等部分，来减少思考的麻烦。