技术文档写作几点建议?

写作技巧2021-06-10 08:22:56admin2

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

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

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

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

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

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

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

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

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

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

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

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

相关推荐

猜你喜欢

大家正在看

换一换