扫描文档不清晰_使文档清晰明了的10个技巧

扫描文档不清晰

因此，您有一些出色的书面文档。 怎么办？ 现在是时候回去编辑它了。 当您第一次坐下来编写文档时，您希望专注于您要说的内容，而不是怎么说的方式，但是，一旦完成初稿，就该回头并稍作整理。

我最喜欢的编辑方式之一就是朗读我写的东西。 这是捕捉尴尬的短语或句子结构的最佳方法，这些短语或句子结构在您自己阅读时可能不会突出。 如果您大声朗读时听起来不错，可能是这样。 如果您的文档恰好包含说明，则可以观察有人尝试遵循它们。 这提供了有关缺少或不清楚的步骤的良好反馈，尤其是如果此人不熟悉该主题时。

找一个好作家的人阅读并编辑所写的内容也很有帮助。 我为Opensource.com撰写文章的最喜欢的好处是，我有出色的编辑人员在我的作品上线之前对其进行审查（请阅读： 为Opensource.com做出贡献的7个主要理由 ）。

在澄清文档时，需要寻找以下十件事。

主动与被动语音

在大多数情况下，您应该首选主动声音。 可以直接说。 您如何检查被动语音？ 插入单词“ by zombies ”。 例如，说“如果单击'是'，将删除您的数据”，而不是“如果单击'是'，将删除数据”。 将僵尸测试应用于以下两个示例：

• “如果单击'是'，您将按僵尸删除数据。”
• “如果单击'是'，则僵尸将删除数据。”

在第一个示例中，毫无疑问您是演员。 第二个示例表明存在误解的空间。 非常清楚地指出哪些演员在执行动作。

消除行话

有些术语是不可避免的，但为清楚起见，应尽可能避免使用。 第一次使用时，链接到术语的定义是可以接受的，并且还应该编写自己的简要定义。 您不想依靠外部站点的可用性，或者不想让您的读者无数次地了解您的文档。

检查常见错误

质疑所有您认为自己知道的事物，并利用指尖触及的世界来查找所有事物。 例如，“ eg”表示“例如”，而“ ie”表示“换句话说”。 “效果”是名词（如xkcd所示， 除非是 ， 否则为名词），“效果”是动词。 当可以从句子中删除一个子句而不改变其含义时，请使用“ that”；如果不能，则使用“ that”。

删除悬空修改器

当不清楚某个单词或短语正在修改哪个对象时，就创建了一个悬空修改器 。 一个典型的例子是“饿了，剩下的食物被吞噬了”。 饿是食物的名字吗？ 如果您的意思是在“食物”之后添加逗号。 如果不是，请将其重写以使您的意思清楚：“您的作者饿了，吞噬了剩下的食物。” 仔细组织句子； 不要强迫读者猜测你的意思。

查看您的风格指南

如果您的项目或公司有文档的样式指南，请检查所写内容是否符合该指南。 一个常见的错误是公司和项目名称的缩写。

避免说不清楚的话

您知道在撰写本文时删除了“经常”和“一些”之类的词的次数吗？ 我不知道确切多少，但我知道这是一个非零的数字。 使用具有特定含义的词。 当您试图说服读者您告诉他们的内容很重要时，这尤其重要。 如果我说“遵循这些技巧可以使您的写作更好”，那么它的说服力就不如“遵循这些技巧将使您的项目的财务贡献增加45％”。 如果您使用模糊的单词来捉住自己，请问问自己您是否真的了解自己的主题，或者是否正在尝试隐藏某些东西。

检查单词顺序

英语没有用于修饰名词的形式定义的排序结构，但是Matthew Anderson在此推文中描述了一种非正式的结构：观点大小年龄形状颜色起源材料用途名词。 这是说英语的母语人士知道的，但不知道我们知道的。 彼得·索科洛夫斯基（ Peter Sokolowski）提出建议， 将“ nounier”词放得更靠近名词 。 如果这样做没有帮助，您可以阅读对他的答复的讨论，其中包含许多示例和解释。

删除“ just”和“ simply”之类的词

技术并不像我们想像的那样简单。 如果您告诉读者一些简单的事情然后他们做不到，那么他们会怎么想呢？ 除非您要为最新的必备厨房小工具编写信息电视，否则请不要使用这些文字。

检查你的代词

当您说“我们”时，您真正的意思是谁？ 我看过以所谓的“烹饪表演风格”编写的文档，其中“接下来，我们单击whatchamadoozit来使摇摇晃晃的东西摇摇欲坠”。 在支持环境中写作时，弄清谁在做什么尤为重要。 如果您告诉某人“我们可以更改该设置”，那么他们希望您会为他们做，而不是他们可以在您的指导下完成。 作为一般规则，除非我谈论自己是作者或代表的组织，否则请避免使用第一人称（I / we）。 如有疑问，请用第三人称自己（例如“作者建议您用第三人称自己”）。 听起来可能过于正式，但很明显。

删除拆分不定式

不要在“ to”和动词之间插入单词。 您的文档的使命是大胆尝试以前没有做过的文档。 （星舰船长被免除此规则）。

您还有其他喜欢的技巧吗？ 让我们在评论中知道。

翻译自: https://opensource.com/life/16/11/tips-for-clear-documentation

扫描文档不清晰