如何编写清晰简洁的文档

我们的文档存在的问题

作为软件工程师，我们大多数文档都存在一个问题：当我们决定编写文档时，它往往会变得过于复杂，充斥着专业术语，而且缺乏重点。我们花费大量时间试图确保代码尽可能简洁，却很少考虑如何编写文档。

要想在文档上花更多心思，一个方法就是投入更多时间。但问题是，大多数公司都没有时间去做这件事——好的文档并不一定能带来企业期望的短期效益。

与其花时间仔细推敲你写的每个段落和每个解释，不如考虑以下方法。在写下任何内容之前，花10分钟做一些规划，确定文档的基线和范围。这样的规划不仅可以让你的写作过程更轻松，还能帮助读者最大限度地利用你的文档。让我来详细说明一下。

设定基线

技术写作最难的部分之一或许就是确定受众的技能。您可以向团队或组织发布一个页面，却不知道最终会是谁阅读它。想象一下，您正在撰写一份关于一个非常小众主题的文档，而该主题建立在团队生态系统中的许多其他概念之上。经验丰富的老手阅读这份文档很可能能够轻松理解您的写作。但是，如果团队中的一位新手偶然发现了这份文档并试图通读它，该怎么办？突然之间，这份文档的效果与其预期相反——文档中充斥着各种术语和隐含知识，最终反而让读者对主题更加困惑，而不是更容易理解。

知识基线是指理解任何文档中信息所需的最低限度的信息量。在开始撰写文档之前，请先列出所有你认为读者已知的主题，并按项目符号列出。将此项目符号列表放在页面顶部，单独列出一个部分——或许可以将此部分标记为“基线”。

以下是我为学习 Redux 的页面设置的基准示例：

# Starting out with Redux

## Baseline

- Knowledge of React, particularly in: components, state, lifecycle, hooks
- Functional programming concepts: pure functions, side effects
- Immutability

在页面顶部定义基线可以起到一些作用。

它使编写变得更容易。通过定义基线，您可以定义一组现在隐含的最低限度的知识。您不再需要描述基线中列出的任何主题的任何细节。技术术语现在变得更有帮助，而不是令人困惑——我现在可以在我的 Redux 页面中描述 Reducer 时使用术语“纯函数”，并且确信读者会知道它的含义。这使我可以更加简洁。

它使读者更容易理解你的写作。既然页面顶部设置了明确的预期，读者就可以评估自己已经了解了多少。他们可以选择在继续阅读本文档之前先阅读相关主题，而不是盲目地深入阅读文档。一旦他们准备好了，就可以带着所需的知识回到本文档，通读你的解释。

它能识别生态系统文档中的缺陷。既然您已经编写了基准，就可以逐一查看每个项目，并将其链接到其他资源和文档，以帮助读者学习。这样做的好处显而易见，就是让读者能够访问更多文档，同时也有助于识别文档中缺少的某些主题。请记录这些主题，以便将来补充更多文档。

设定范围

某些文献试图一次涵盖太多内容。在宏观层面上分割主题很容易。考虑编写一套涵盖整个动物界的文献。一个明显需要分隔文档页面的地方就是不同的动物。我们将为孟加拉虎和西北非洲猎豹分别写一个页面。这种区别很明显，但我们真的能够在一页纸上包含关于孟加拉虎的所有信息吗？很可能做不到。我们可以写一个页面介绍孟加拉虎的狩猎习惯，另一个页面介绍它们的栖息地。即使是这些主题也可能过于宽泛。在微观层面上划分主题是微妙的，而且通常是主观的，但最终重要的是要保持你的写作清晰简洁。

范围是指您的文档将涵盖的主题。与设置基准一样，您应该在开始编写页面之前就设定好范围。定义几个要点，概括性地描述您的页面内容。将它们放在页面的基准部分下，并在标题栏中命名为“范围”。

下面是我可能为上面提到的 Redux 页面设置的示例范围。

# Starting out with Redux

## Baseline

...

## Scope

- What problem does Redux solve?
- Application Structure
- The Store
- State, Actions, Reducers

就像定义基线一样，这会为您完成一些事情。

它可以帮助您在微观层面上进行划分。概述页面的预期范围会迫使您考虑在页面上包含哪些内容。如果您注意到范围下列出了许多主题，请考虑将它们分成几个类别，并将这些内容分散到多个页面中。一个范围内的项目过多会导致文档冗长。通常，如果将信息分解成清晰独立的部分，读者会更容易理解。

它能让你的写作保持正轨。现在你已经有了一组概述页面内容的要点，你有一个明确的写作起点。选择一个要点开始写。同样，如果你注意到某个主题开始拖延，可以考虑将其拆分成单独的页面，并为其设定基线和范围。范围还为页面定义了一个清晰的最终状态——一旦为范围列表中的每个项目编写了文档，你就知道大功告成了。定义明确的范围可以使你的文档简洁明了。

它向读者表明了本页将涵盖的内容。如果读者阅读了范围并确定本页未涵盖他们需要学习的内容，他们可以立即离开，而无需浪费时间阅读该页面。如果范围涵盖了他们想要学习的内容，那么他​​们现在就可以确切地知道本页将涵盖哪些内容。预先设定读者的期望，可以让他们在坐下来阅读文档时清楚地了解自己将要面对的内容。

总结

定义基线和范围是两种简单且省时的方法，可以立即改进您的文档。它极大地帮助了写作过程，同时为读者提供了有价值的信息。也许您在动笔之前就已经在内心思考过这两个方面了。像这样将您的想法写在纸上，可以将计划提升到一个新的高度——您已经在思考了，为什么不把它写下来呢？

这份实体合同确保作者忠实于最初的计划。它就像一套指导原则，确保作者始终围绕主题。定义好基线后，无需向读者解释主题 A 的细节——他们已经了解了。定义好范围后，无需超出或少于范围规定的内容。这两个简单的清单有助于使您的文档更加清晰简洁。

如果您喜欢这些内容，请考虑订阅我的邮件列表，以便在我发布新内容时收到通知。