Self-editing

想象一下,您刚刚编写了文档的初稿。 你如何让它变得更好? 在大多数情况下,最终发布的文档是一个迭代过程。 将空白页转换为初稿通常是最困难的一步。 撰写初稿后,请确保留出足够的时间来完善您的文档。

本单元中的编辑技巧可以帮助您将初稿转变为更清晰地传达受众所需信息的文档。 使用一个技巧或全部使用; 重要的是找到一个适合你的策略,然后让这个策略成为你写作程序的一部分。

选取写作风格

公司、组织和大型开源项目经常会采用现有的或编写自己的文档样式指南。Google Developers 网站上的许多文档项目都遵循使用Google开发者文档样式指南。如果你之前完全没有遵照过任何一个文档风格指南,乍一看Google开发者文档样式指南可囊看起来有点吓人,它对语法、标点、格式以及计算机接口界面都有严格要求。你可以先参考文档风格要求的重点部分开始你的写作。

重点部分的一些内容,在<技术文档写作1>进行了介绍。比如说你可能还记得如下一些技巧:

  • 使用主动语态来标记主语。
  • 使用有序列表来呈列有顺序步骤的项目。
  • 使用项目符号列表来呈列其他类型的项目。

重点部分的也列出了一些写作技术文档的其他技巧,例如:

像读者一样思考

你的受众是谁?后退一步,尝试从他们的角度出发重读你的草稿。确保你的文档目标明确,并为读者可能不熟悉的任何术语或概念提供定义。

为您的受众勾勒出一个人格面具可能会有所帮助。人格面具可以由以下任何属性组成:

  • 读者的角色。例如,系统工程师或者测试工程师。
  • 最终目标。例如,恢复数据库。
  • 对读者知识背景或者经验的假设。例如:
    • 熟悉Python。
    • 使用Linux操作系统。
    • 可以舒适地使用命令行进行操作。

代入这样的“人格面具”来检查你的草稿。在文档中列出你的一些假设,对受众理解文档尤其有帮助。你可以提供资源的链接,以便于他们复习某个特定主题时了解更多信息。

请注意,过分依赖一到两个“人格面具”会导致文档内容过于狭隘,无法大部分读者有用。

参看<技术文档写作1>的Audience自学单元来回顾和了解有关读者的信息。

大声朗读

由于不同的背景,你的写作风格可能疏远或吸引读者,甚至使你的读者厌烦。文档该呈现什么样的风格,一定程度上取决于受众。例如,旨在招募项目贡献者的新开源项目的贡献者指南,可能采用非正式且更口语化一点的风格。而商业软件的开发者指南会采用更正式的风格。

大声朗读你的草稿,以此来检查文档是否是口语化的。注意那些尴尬的措辞,过长的句子,或任何其他感觉不自然的东西。你也可以使用屏幕阅读器为你朗读文档。

了解更多信息,可以参考风格和作者语气一文。

稍后再看

写完文档的初稿(或二稿、三稿)后,先将其放在一边。在一个小时后(或两三个小时候)再来读你的草稿,你几乎总能找到一些可以改进的部分。

换个环境

一些作者习惯于将文档打印出来,并用红笔标注的方式来检查草稿。通过对阅读环境的变化,你也可以检查出可以改进的地方。对于这个经典技巧的一种现代诠释是,你可以将草稿拷贝到另外一个文档内,修改文本的字体、大小和颜色。

找到同行“编辑”

正如工程师需要其他同行帮忙检查代码一样,文档作者也需要同行“编辑”给予反馈。请人帮你审阅文档,提出具体的建设性意见。您的同行“编辑”不需要是文档技术主题方面的专家,但至少要对你文档遵循的风格是熟悉的。

习题

如果你手头有一个正在处理的文档,使用本单元的技巧来优化它。若没有,可以尝试着对下面这段话进行优化:

Determine whether or not you can simplify your document through the use of terminology that is equivalent but relatively shorter in length and therefore more easily comprehensible by your audience. It's important to make sure your document is edited before it is seen by your audience, which might include people that are less or more familiar with the matter covered by your document. The first thing you need is a rough draft. Some things that can help make your document easier to read are making sure you have links to background information, and also checking for active voice instead of passive voice. If you have long sentences you can consider shortening them or implementing the use of a list to make the information easier to scan.

Reference

原文:https://developers.google.com/tech-writing/two/editing

Copyright @ Lambert 2022 all right reserved,powered by GitbookModified Time: 2024-02-24 14:20:10

results matching ""

    No results matching ""