文档应该简洁、一致且简单

还没有读者喜欢这篇文章。
Typewriter keys

April Killingsworth。Rikki Endsley 修改。CC BY-SA 2.0 许可。

“词语是有意义的”是我最喜欢的表达之一。我经常在玩笑中使用它,但在编写文档时,这是一个重要的考虑因素。我通常是一个喜欢用艺术天赋挥洒文字的人,但当涉及到编写技术文档时,我在措辞上变得更加谨慎。我不知道这种习惯是什么时候开始的,但我注意到多年来,我在用词方面变得越来越小心。本文介绍了三个注意事项和相关的资源,您在写作时可以牢记这些。

精通技术的作者习惯于像他们精通技术一样写作。不幸的是,读者并不总是那么精通,特别是当他们是项目新手时。最好使用简单、明确的术语,并解释新的或特定于主题的术语。IEEE 专业传播协会在如何清晰地选择词语方面提供了出色的指导

以从未使用过电脑的人作为一个极端的例子。习惯“点击”涉及鼠标(或触控板),而“按下”涉及键盘的想法可能需要一段时间才能适应。如果文档开始交替使用这些术语,读者可能会感到困惑。更有经验的读者将能够从上下文中找出正确的操作,但是这种不一致性对于刚开始学习计算机基本知识的人来说可能会令人感到不适。

正确选择词语还有另一个优点:读者花在弄清楚你的意思上的时间越少,他们就可以花更多的时间在你试图表达的内容上。如果你的文档和别人的文档都使用了前后一致的词语,那么你的读者的生活就会变得更好一些。微软有一个全面的用户交互术语词汇表

词语选择的一致性不仅对你的读者有帮助,对你的翻译人员也有帮助。字符串越一致,翻译所涉及的工作量就越少。

说到翻译,更简单的词语减少了翻译人员在找到正确的翻译之前必须查找单词的次数。坚持使用常用词语也有助于你以读者更可能理解的方式解释概念。XKCD 漫画Up Goer Five就是一个很好的例子。牛津 3000™ 词汇表是一个很棒的常用词汇列表。当然,使用更简单的词语通常意味着使用更多的词语,因此简单和简洁常常是矛盾的。如果你了解你的受众,你就可以达到适当的平衡。

所以请记住,当您写作时:要简洁、要一致、要简单。词语是有意义的。

标签
User profile image.
Ben Cotton 接受过气象学家的培训,但天气是一个很棒的爱好。Ben 在红帽公司担任 Fedora 项目经理。他是《开源项目项目管理》一书的作者。在 Twitter (@FunnelFiasco) 或 FunnelFiasco.com 上找到他。

7 条评论

关于文档的另一点是,它需要解释如何使用某物(软件、硬件),而不是所有按钮的功能。例如,我如何使用我的新 CD 音响与用户指南不同,用户指南会继续介绍按钮、模式等。人们想知道如何看时间,而不是时钟的内部工作原理。大多数 Linux 应用程序的用户文档似乎都侧重于按钮和模式,而不是告诉用户如何实际使用该应用程序。

这是一个很好的观点。“这里有一个包含所有可能选项的巨大列表”是有用的,但它应该是“如何使用这个东西!”的附录。

回复 ,作者:dave (未验证)

为了补充翻译建议 - 今天的大部分翻译最初是由机器完成的,然后由翻译人员进来验证/修复任何问题。不仅词语选择的一致性,短语的一致性也可以从长远来看节省 $$,因为机器会学习短语,然后每次重复该短语时都可以翻译。(这里没有使用确切的本地化术语,但希望大家明白这个意思)。

还有一个日益增长的趋势是让作者也参与到应用程序的 UX/UI 中,以帮助解决定义每个按钮的需求。通过内置于应用程序的上下文帮助,用户可以右键单击或悬停等来获得即时的“按钮”定义。这让文档可以专注于诸如“如何使用这个东西!”之类的有趣事情 :-)

良好的意图和一些好的建议,但需要澄清一些内容。简单语言和简单文档之间存在真实而重要的区别。

文档应该清晰明了。在文档和其他写作中使用简单语言(通常称为朴素语言)有很多好处。但是,这并不意味着文档本身需要简单。有时文档应该是复杂的 - 包括复杂的信息。文档的简单性(或复杂性)应根据受众和文档的目的而变化。

作者应该了解受众的需求和知识,然后适当地写作。例如,为安装软件的经验丰富的工程师编写的有效的管理指南与为同一软件的非技术最终用户编写的指南会有所不同。熟练的作者应该能够评估他们的潜在读者(进行受众分析)并相应地调整他们的写作。

有很多关于朴素语言的信息。对我来说,我发现首字母缩写词 KISS - Keep It Simple Stupid - 是一个很好的提醒,并且通常对任何作家都是很好的建议。不要过度写作或提供过于复杂的信息。在你的文档中要直接和直截了当。

对于文档,我一直建议遵循 4C 原则。正确 (Correct) - 清晰 (Clear) - 简洁 (Concise) - 一致 (Consistent)。对此有一些变体 - 有时包括全面 (Comprehensive) 和其他 C 开头的词。我认识的最优秀的作家都在不断挑战自己。

感谢您的评论,Mary。这是一个很好的建议(如果您稍微扩展一下,它本身可能就是一篇好文章)。我同意了解并适当地定位受众是关键。

回复 ,作者:Mary Arrotti (未验证)

关于术语的简单说明:写关于“...术语表”是同义反复(重复相同的术语),因为 _术语表_ 本身就是术语列表...

回复 ,作者:bcotton

Creative Commons License本作品采用知识共享署名-相同方式共享 4.0 国际许可协议进行许可。
© . All rights reserved.