因此，您已经编写了一些出色的文档。然后呢？现在是时候回去编辑它了。当您第一次坐下来编写文档时，您希望专注于您想要表达的内容，而不是您表达的方式，但是一旦初稿完成，就该回去润色一下了。
我最喜欢的编辑方式之一是大声朗读我写的内容。这是捕捉尴尬措辞或句子结构的最佳方法，这些措辞或句子结构在您自己阅读时可能不会突出显示。如果您大声朗读时听起来不错，那可能就是不错的。如果您的文档恰好包含说明，您可以观察某人尝试遵循这些说明。这为缺少或不清楚的步骤提供了良好的反馈，特别是当这个人不熟悉该主题时。
让一位优秀的作家阅读和编辑您写的内容也很有帮助。我为 Opensource.com 写作最喜欢的好处是，在我作品上线之前，我有优秀的编辑来审查我的作品（阅读：为 Opensource.com 贡献内容的 7 个重要理由）。
以下是您在澄清文档时需要注意的十件事。
主动语态与被动语态
在大多数情况下，您应该首选主动语态。直接一点是可以的。您如何检查被动语态？插入词语“被僵尸”。例如，说“如果您单击‘是’，您将删除您的数据”比说“如果您单击‘是’，数据将被删除”要清楚得多。将僵尸测试应用于以下两个示例
- “如果您单击‘是’，您将被僵尸删除您的数据。”
- “如果您单击‘是’，数据将被僵尸删除。”
在第一个例子中，毫无疑问您是执行者。第二个例子表明存在误解的空间。清楚地说明哪些执行者执行哪些操作。
消除术语
一些术语是不可避免的，但为了清晰起见，您应尽可能避免使用它们。第一次使用术语时链接到术语的定义是可以接受的，并且您还应该编写自己的简短定义。您不希望依赖外部站点的可用性，或者让您的读者跳过太多的障碍来理解您的文档。
检查常见错误
质疑您认为您知道的一切，并利用触手可及的世界，查找一切。例如，“e.g.”表示“例如”，“i.e.”表示“换句话说”。 “Effect”是名词（除非不是，正如 xkcd 漫画所示），而“affect”是动词。当从句子中删除从句不会改变含义时，使用“which”，当不能删除时，使用“that”。
删除悬垂修饰语
当不清楚哪个对象被单词或短语修饰时，您就创建了一个悬垂修饰语。一个经典的例子是“饿了，剩下的食物被狼吞虎咽”。 “Hungry”是食物的名字吗？如果是这个意思，在“food”后添加逗号。如果不是，请重写它以使您的意思明确：“您的作者饿了，狼吞虎咽地吃掉了剩下的食物。”仔细组织您的句子；不要强迫您的读者猜测您的意思。
检查您的风格指南
如果您的项目或公司有文档风格指南，请检查您编写的内容是否符合该指南。一个常见的错误是不恰当地缩写公司和项目名称。
避免使用不明确的词语
您知道我在写这篇文章时删除了多少次“经常”和“一些”之类的词语吗？我不知道具体有多少次，但我知道这是一个非零数字。使用具有特定含义的词语。当您试图说服读者您告诉他们的内容很重要时，这一点尤为重要。如果我说“遵循这些技巧会让您的写作更好”，那就不如“遵循这些技巧将使您的项目的财务贡献增加 45%”那么有说服力。如果您发现自己使用了模糊的词语，请问问自己是否真的理解您的主题，或者是否可能试图隐藏某些东西。
检查词序
英语语言没有正式定义的修饰名词的排序结构，但是存在一个非正式结构，Matthew Anderson 的这条 推文 中描述了该结构：观点-大小-年龄-形状-颜色-来源-材料-目的 名词。这是以英语为母语的人知道的东西，但不知道我们知道。 Peter Sokolowski 回复建议 将“名词性”词语放在更靠近名词的位置。如果这没有帮助您阅读他对他的回复的讨论，其中有许多示例和解释。
删除“just”和“simply”之类的词语
技术并不像我们喜欢假装的那样简单。如果您告诉您的读者某些东西很简单，然后他们做不到，他们会怎么看待自己？除非您正在为最新的必备厨房小工具撰写电视购物广告，否则请省略这些词语。
检查您的代词
当您说“我们”时，您真正指的是谁？我见过用我称之为“烹饪节目风格”编写的文档，其中“接下来我们点击 whatchamadoozit 来 fribble the wozulator。”当您在支持环境中写作时，尤其重要的是要清楚谁做什么。如果您告诉某人“我们可以更改该设置”，他们会期望您为他们这样做，而不是他们可以在您的指导下做到这一点。作为一般规则，我避免使用第一人称（我/我们），除非我谈论自己作为作者或我所代表的组织。如有疑问，请用第三人称称呼自己（例如“作者建议您用第三人称称呼自己”）。这听起来可能过于正式，但很清楚。
删除分裂不定式
不要在“to”和动词之间插入单词。您的文档的任务是勇敢地前往前所未有的领域。（星舰舰长可免除此规则）。
您还有其他喜欢的技巧吗？请在评论中告诉我们。
12 条评论