编写有效技术文档的策略

自 1999 年以来，我一直在从事各种技术写作，当时我为 Altec Lansing 位于以色列 Kfar Saba 的研发部门进行质量保证。那时我们会推出创新的、与音频相关的设备，例如（喘息）可在 Windows ME 和 2000 上运行的 USB 音频设备。它们有缺陷，并且设置它们并不像今天那么简单。

我们需要文档。

我们遇到了一些用户必须跳过的难题，我们需要一种方法来记录它们是什么、边缘情况是什么，以及如何诊断和修复所有这些问题。它需要包装精美、格式清晰，并且可供安装我们的帮助应用程序的用户访问。我找到了 Robohelp 应用程序，它用于在 Windows 上创建标准帮助应用程序，并将帮助文件添加到我们的安装中。

在我们的质量检查过程中，我们将识别问题，记录我们认为重要的内容，并将其组织到与设备捆绑在一起的帮助文件中。当时我 19 岁，对这些东西的经验为零，这是一个非常幼稚的过程。尽管如此，这对我们的用户来说似乎是正确的事情，而且我的经理并没有明确告诉我不要这样做。

24 年过去了，从那时起我已经为很多项目编写了文档。规模不断扩大，我看待此类项目的方式也发生了巨大变化。

我对什么是优秀文档有一些想法，如果您感兴趣，我很乐意与您分享。

核心文档概念

我想从一组更具体的规则开始，我认为这些规则对于文档产品的成功至关重要。

• 文档应该使用小词来描述大想法- 因此不要使用华丽的词或复杂的句子来描述可以用更简单的术语表达的内容。你会一路失去用户，这不值得你的作家自负。

• 文档应该尽可能讲述一个故事- 因为一组个人的、相关的讲述故事的任务比一组抽象的指令对用户来说更有吸引力、更容易记住。

• 文档应该是可搜索的- 因为说真的：这是理所当然的。如果您的文档不容易找到内容，您的用户将找不到他们需要的内容。

• 文档几乎总是更大战略的一部分- 对于软件产品尤其如此。这涉及到开发人员倡导的更大主题，但简而言之：您的文档应该得到视频教程、实际使用示例和实时技术支持的支持。

• 文档应该经过测试- 因为您可能确定一切都是正确的，但如果没有真正的用户，就像任何其他产品一样，您将无法确定。测试并再次测试。

  
  

整体文档是精心设计的产品

当您学习一种新的编程语言时，该语言中的概念和想法就会流入您的解决问题技巧中。它让你成为一名更好的软件开发人员，最终，你会开发出更好的软件，因为你更有意识、更有能力。

我的职业生涯很复杂，包括很多软件产品设计、软件开发、技术支持和开发人员宣传。每个学科都影响了我思考和对待他人的方式。

当我着手技术写作项目时，我会对用户的需求有一个广泛的了解。我认为这是思考文档的正确方式：整体。文档并不是一个明确定义的东西，要制作出好的文档，您必须保持灵活性。

对我来说，这意味着您必须从尽可能多的角度考虑您的用户。您不能认为任何事情都是理所当然的，否则您会让某些用户群体失望，从而对您的品牌、产品或业务产生难以挽回的负面影响。

对于用户来说，您的文档通常是决定成败的体验。

如果你做得好，你的用户将成功使用你的产品，并成为你品牌的拥护者。如果你不这样做，他们可能永远不会再使用你的产品，因为你的文档在他们心中留下了不好的印象。他们也会让其他人知道。良好的营销从这里开始，所以请记住这一点。

制作好的文档

制作好的文档仅仅意味着您必须像对待任何其他产品流程一样创建文档。

你需要：

• 知道为什么要创建文档
• 了解您的目标受众是谁
• 了解他们的痛点是什么
• 随着时间的推移改进您的文档

让我们仔细看看其中每一个。

了解文档的原因通常是表面上非常简单的问题和答案。您正在创建文档，因为如果您不这样做，用户就会陷入困境并无法使用您的产品。在更深层次上，您的用例有一个具体的答案。有开发者工具吗？这是一组答案。有零售设计工具吗？有会计 SaaS 产品吗？有自动咖啡机吗？这些都是单独的答案集。

您的文档的形式由使用它的人来描述。在线吗？它与应用程序捆绑在一起吗？是打印出来的吗？每个用户群都需要其他东西，你必须从一开始就清楚他们是谁。

您的工作是找出每个用户面临的困难，并围绕通过解决他们的特定问题的信息内容来引导他们编写文档。

最重要的是，您必须知道您可能不会第一次就把事情做好。这意味着随着您的产品随着时间的推移而增长和变化，您的文档需要维护和更新。希望这是在某个框架内完成的，以便与您试图帮助的用户轻松沟通。您必须与用户交谈，倾听他们的需求，并尝试使用您的文档来改善他们使用您产品的体验。

您的文档是您成功不可或缺的一部分

我将通过简单地强调文档的重要性来总结。没有它们，您的用户就只能靠自己，必须自力更生。

这总是意味着更少的成功案例、生态系统中对产品的看法更差、开发人员或用户更不满意，以及对您的品牌或公司产生负面影响。

文档本身就是一个重要的子产品，是一项投资，并且必须成为更广泛的产品策略的一部分。