扫描文档不清晰_使文档清晰明了的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

扫描文档不清晰

    原文作者:cumo3681
    原文地址: https://blog.csdn.net/cumo3681/article/details/107394165
    本文转自网络文章,转载此文章仅为分享知识,如有侵权,请联系博主进行删除。
点赞