Documents

你可以写出句子，也可以用句子组成段落。你能将这些段落组织成连贯且一致的文档吗？

声明文档范围

一篇好的文档从定义其范围开始。例如：

This document describes the design of Project Frambus.

一篇更好的文档，还会定义其未覆盖的范围，目标受众可能合理地期望你的文档说明其未涵盖的主题。例如：

This document does not describe the design for the related technology, Project Froobus.

涵盖以及未涵盖范围声明不仅有利于读者，也对作者本人有益。当写作时，若文档内容偏离了涵盖声明时（或讨论到未涵盖的范围时），那么你必须重新将文档内容聚焦在声明的范围内、或者修改范围声明。在审阅文档初稿时，删除任何与覆盖范围无关的部分。

练习

下面段落有什么问题？

This document explains how to use the Frambus API to create, update, and publish Fwidgets. This document does not explain how to use the Frambus API to delete Fwidgets or cover the history of the Linux operating system.

声明受众

好的文档应该明确声明其受众。例如：

This document is aimed at the following audiences:

• Software Engineers
• Program Managers

除了受众角色外，好的受众声明还会指定任何先决知识或经验。例如：

This document assumes that you understand matrix multiplication and the fundamentals of backpropagation.

某些情况下，受众声明还需要指出读本文前需要先预读的课程。例如：

You must read "Project Froobus: A New Hope" prior to reading this document.

段首即总结关键点

工程师和科学家都是大忙人，可能没有时间读完你76页整的设计文档。想象以下，和你一样的这群人可能只会读你文档的第一段。因此，请确保文首会回答读者的核心问题。

有经验的文档作者将大量精力集中在第一页上，以增加读者进入第二页的几率。然而，任何长文档的开头都是最难写的一页。因此，请做好多次修改第一页的思想准备。

比较和对比

无论你多么有创造力，在你的职业生涯中，你也只会写出极少量的真正具有革新性内容的文档。你的大部分工作只是在现有的技术和概念上演进。因此，在文档中将你的想法与读者已知的概念做比较和对比。例如：

This new app is similar to the Frambus app, except with much better graphics.

或

The Froobus API handles the same use cases as the Frambus API, except that the Froobus API is much easier to use.

练习

下面的说明段落有什么问题？

Frambus Weather app v2 introduces ten features not available in Frambus Weather app v1. Most importantly, v2 offers two-week forecasts, v1 offered only one-week forecasts. Tidal information won't change.

为受众写作

本课程反复强调定义的重要性。在本节中，我们重点关注受众定义如何成为组织文档的一种方式。

确定受众需求

回答以下问题，可帮助您确定文档应包含的内容：：

• 目标受众是谁？
• 目标受众的目标是什么？为什么他们要读这个文档？
• 在读这篇文档前哪些是他们已知的？
• 读完这篇文档后，读者可以知道或学会做什么？

例如，假设你发明了一个类似快速排序的新排序算法，如下列表包含了针对上述问题的一些潜在回答：

• 目标受众是谁？组织内的所有软件工程师。
• 目标受众的目标是什么？目标受众的目标是更有效数据排序方式。他们读这篇文档以确定新排序算法是否值得实作。
• 在读这篇文档前哪些是他们已知的？目标受众知道如何编程，也学习过各种排序算法（包括快速排序）。然而，他们已经很多年没有实作或者评估过排序算法了。
• 读完这篇文档后，读者可以知道或学会做什么？读完文档后，目标受众将可以做以下所有事情：
  • 了解新算法和快速排序算法对比信息。
  • 了解新算法优于快速排序的两种数据集。
  • 使用他们熟悉的编程语言来实作新算法。
  • 了解到新算法表现不佳的两种边际条件。

组织文档满足受众需求

在定义了受众的需求之后，组织文档以帮助读者获得他们需要的信息。例如，根据上一节的答案，文档的大纲可能如下所示：

1. Overview of the algorithm
   • Compare and contrast with quicksort, including Big 0 comparisons
     • Link to wikipedia article on quicksort
   • Optimal datasets for the algorithm
2. Implementing the algorithm
   • Implementation in pseudocode
   • Implementation tips, including common mistakes
3. Deeper analysis of algorithm
   • Edge cases
   • Known unknowns

Reference

原文: https://developers.google.com/tech-writing/one/documents