技术文档写作几点建议
2013-01-10 17:28
253 查看
任何新技术,新方法的文档和书记都大致分为两类。
第一类是官方手册,是白皮书,对该技术有最权威的解释权,由技术提出者维护。此类文档一般只是枯燥的记录功能条目,其作用等价于字典(没人会拿着字典从第一页看到最后一页看完)。优点是给该技术提供了一致的解释权,该技术对于使用者有根基可循,缺点是相对枯燥不适合用来技术传播。
第二类是技术使用者根据自己经验写的类似于“最佳实践”的材料,里面融合和作者个人看法,相对比较生动,组织也很吸引人。优点是有想法,适合用于技术传播,缺点是比较主观,个别观点未见得准确或者说有偏见。
当两部分材料结合在一起就能发挥最大的作用。
下面分享几点技术文档写作建议(中英文),通用于上述两种。
1. 应尽量避免使用“你”,“We can”,“You should”这样的称谓,取而代之应该使用“用户”,"Users"这种更通用的称谓。
2. 尽量多使用忽略动作发出者的被动句子。
3. 在引用代码和脚本时候应使用特殊字体标出,必要时还原其在开发环境中存在时的色彩。
4. 文中特殊名词应该用黑体或者粗体标识出来,以提醒读者此处是一个专有名词,而非宽泛的叙述。
5. 当在文中用中文提出一个行业名词时,尽量在后面用英文写出其原文,让已知此概念读者方面对照,并告知不知此概念读者此概念非你所造而是有出处。
6. 尽量少用“可惜”,"unfortunately"这种带有主观情绪的形容词和副词。
7. Bullet或者Numeric列条目时,动作要使用原型动词引导的祈使句,比如 Create a new account.
第一类是官方手册,是白皮书,对该技术有最权威的解释权,由技术提出者维护。此类文档一般只是枯燥的记录功能条目,其作用等价于字典(没人会拿着字典从第一页看到最后一页看完)。优点是给该技术提供了一致的解释权,该技术对于使用者有根基可循,缺点是相对枯燥不适合用来技术传播。
第二类是技术使用者根据自己经验写的类似于“最佳实践”的材料,里面融合和作者个人看法,相对比较生动,组织也很吸引人。优点是有想法,适合用于技术传播,缺点是比较主观,个别观点未见得准确或者说有偏见。
当两部分材料结合在一起就能发挥最大的作用。
下面分享几点技术文档写作建议(中英文),通用于上述两种。
1. 应尽量避免使用“你”,“We can”,“You should”这样的称谓,取而代之应该使用“用户”,"Users"这种更通用的称谓。
2. 尽量多使用忽略动作发出者的被动句子。
3. 在引用代码和脚本时候应使用特殊字体标出,必要时还原其在开发环境中存在时的色彩。
4. 文中特殊名词应该用黑体或者粗体标识出来,以提醒读者此处是一个专有名词,而非宽泛的叙述。
5. 当在文中用中文提出一个行业名词时,尽量在后面用英文写出其原文,让已知此概念读者方面对照,并告知不知此概念读者此概念非你所造而是有出处。
6. 尽量少用“可惜”,"unfortunately"这种带有主观情绪的形容词和副词。
7. Bullet或者Numeric列条目时,动作要使用原型动词引导的祈使句,比如 Create a new account.
相关文章推荐
- 中文技术文档的写作规范
- 给IT技术入门者的几点建议
- 中文技术文档的写作规范
- 对IT同行的几点建议(不适用于技术狂热主义者)
- 中文技术文档的写作规范
- 中文技术文档的写作规范(转)
- 我最喜爱的十大技术文档写作工具
- 中文技术文档的写作规范
- 制作技术培训演示文档(PPT)的一些经验和建议
- 中文技术文档的写作规范
- 技术文档写作的职业探讨
- 中文技术文档的写作规范
- 阮一峰:中文技术文档的写作规范
- 中文技术文档的写作规范
- 制作技术培训演示文档(PPT)的一些经验和建议
- 我见过的给技术工程师的最好的写作建议(转贴)
- 技术人生:老工程师给毕业生的几点建议(转)
- 中文技术文档的写作规范
- 中文技术文档的写作规范
- 怎么学习电脑技术?给初学者的几点建议