更新时间：2021-06-09 10:13:48作者：admin2
任何新技术，新方法的文档和书记都大致分为两类。
第一类是官方手册，是白皮书，对该技术有最权威的解释权，由技术提出者维护。此类文档一般只是枯燥的记录功能条目，其作用等价于字典（没人会拿着字典从第一页看到最后一页看完）。优点是给该技术提供了一致的解释权，该技术对于使用者有根基可循，缺点是相对枯燥不适合用来技术传播。
第二类是技术使用者根据自己经验写的类似于“最佳实践”的材料，里面融合和作者个人看法，相对比较生动，组织也很吸引人。优点是有想法，适合用于技术传播，缺点是比较主观，个别观点未见得准确或者说有偏见。
当两部分材料结合在一起就能发挥最大的作用。
下面分享几点技术文档写作建议（中英文），通用于上述两种。
1. 应尽量避免使用“你”，“We can”，“You should”这样的称谓，取而代之应该使用“用户”，"Users"这种更通用的称谓。
2. 尽量多使用忽略动作发出者的被动句子。
3. 在引用代码和脚本时候应使用特殊字体标出，必要时还原其在开发环境中存在时的色彩。
4. 文中特殊名词应该用黑体或者粗体标识出来，以提醒读者此处是一个专有名词，而非宽泛的叙述。
5. 当在文中用中文提出一个行业名词时，尽量在后面用英文写出其原文，让已知此概念读者方面对照，并告知不知此概念读者此概念非你所造而是有出处。
6. 尽量少用“可惜”，"unfortunately"这种带有主观情绪的形容词和副词。
7. Bullet或者Numeric列条目时，动作要使用原型动词引导的祈使句，比如 Create a new account.