任何新技术，新方法的文档和书记都大致分为两类。

第一类是官方手册，是白皮书，对该技术有最权威的解释权，由技术提出者维护。此类文档一般只是枯燥的记录功能条目，其作用等价于字典（没人会拿着字典从第一页看到最后一页看完）。优点是给该技术提供了一致的解释权，该技术对于使用者有根基可循，缺点是相对枯燥不适合用来技术传播。

第二类是技术使用者根据自己经验写的类似于“最佳实践”的材料，里面融合和作者个人看法，相对比较生动，组织也很吸引人。优点是有想法，适合用于技术传播，缺点是比较主观，个别观点未见得准确或者说有偏见。

当两部分材料结合在一起就能发挥最大的作用。

下面分享几点技术文档写作建议（中英文），通用于上述两种。

1. 应尽量避免使用“你”，“We can”，“You should”这样的称谓，取而代之应该使用“用户”，"Users"这种更通用的称谓。

2. 尽量多使用忽略动作发出者的被动句子。

3. 在引用代码和脚本时候应使用特殊字体标出，必要时还原其在开发环境中存在时的色彩。

4. 文中特殊名词应该用黑体或者粗体标识出来，以提醒读者此处是一个专有名词，而非宽泛的叙述。

5. 当在文中用中文提出一个行业名词时，尽量在后面用英文写出其原文，让已知此概念读者方面对照，并告知不知此概念读者此概念非你所造而是有出处。

6. 尽量少用“可惜”，"unfortunately"这种带有主观情绪的形容词和副词。

7. Bullet或者Numeric列条目时，动作要使用原型动词引导的祈使句，比如 Create a new account.