前言
我这两天翻了下国内的一些文档规范,发现基本都是规范格式,缺乏对写文档的通用思路,所以写一个通用的写文档思路。
写前准备
写之前要做的东西并不多,大的方面就两个:
- 规范术语:规范技术文档中用到的专业术语,中文互联网一个导致谬误丛生的原因就是各种同义词乱飞,因此很有必要再一开始就确定专业术语,约定隐喻是什么。如果中文不好表达,可以一开始就使用英文规范
- 对阅读者建模:文档最终是要给人看的,表达的方式要根据阅读者的身份变化。从我个人的角度来看,如果是给 QA/PM 看的文章,那么务必保持术语的通俗易懂,尽量使用平易的语言,同时逻辑递增要保持渐进性,不能上来就什么“hash”加密,
写作要点
编写文档的时候,注意的要点要跟随文章类型变化。但是有一些通用的方法可以使用。
- 文档编写者首先要具体地陈述问题,换言之要写出原有功能 /设计的局限性,该功能处于那一层?为什么要在本层做?有什么不足?这点写出来,就可以继续向下进行。
- 因为有不足,自然就会有客户提出需求,需要给出来客户最开始的原始需求是什么,需求经过了什么变化,为什么会有这种变化,如果是多方需求要写清楚每一方需求的变化。
- 客户的需求阐明了,下一步就是简述我们做的工作是什么,设计时考虑了哪些细节。一般我写这块的时候都是按照原有协议层次的方式来进行描写 1 每层具体提供了什么功能,可以依托现有协议地层次,或者依托功能划分地层次进行描述; 2 给出每一层我们依赖地第三方 /基础功能,并说明每层对上层提供地保证和利用的下层的依赖。层次之间的够通也需要说清楚。
写后总结
写后总结并不是总结这次写的哪里不好,而是一个总的收尾工作。同样需要考虑阅读者是谁来决定怎么写
- 阅读者是客户,那么需要给出详尽的用户使用场景及提示信息,交互信息
- 阅读者是 QA,需要给出具体的 TestConsiderration 与针对的 TroubleShooting
- 阅读者是开发,需要给出系统设计的基本逻辑,给出系统设计时的取舍。
- 无论阅读者是谁,最后都要加上 Security Consideration,即安全性考虑。
结尾碎碎念
如果觉得上面的思考过于麻烦,不如使用机械的手段,直接将文档分为:术语规范;问题描述;客户需求;详尽描述; TestConsiderration ;。。。等部分,来减少思考的麻烦。