建立产品文档策略：一个实用模板

在任何组织中，确定文档的优先顺序都可能是一场斗争，但根据我的个人经验，精心设计的文档策略可能会使这场斗争看起来不那么真实。下面包含的是我个人过去用来建议和推广良好的文档标准的模板。虽然它远不是一个包罗万象的战略，但它已经很好地概述了与业务相关的文档的挑战和目标，并确定了解决这些挑战和目标的策略。

本文档的目的是建立一个持续创建和维护产品文档的策略。这里的主要驱动因素是确保我们面向客户的工具(如API以及移动和Web应用程序)的文档准确且可用。

在讨论生成文档的目标和策略之前，在设计文档策略时，有几个未回答的问题应该牢记在心：

所有文档的质量和有效性，无论是什么产品或目标受众，都可以用三个特征来衡量：可读性、准确性和可发现性。虽然这些特征通常用于确定文档质量，但它们也可以用于建立创建文档策略的目标。

顾名思义，可读性就是一组文档的“可读性”。虽然散文是文档中的一个重要因素，但可读性在很大程度上考虑了文档的目标用户以及如何编写文档。

与产品开发一样，确定一组文档将由谁使用会极大地影响文档的创建方式。建立一个或多个读者角色将定义文档的技术和详细程度。这里需要注意的是，为营销活动和可用性计划建立的用户角色可能不一定与用于文档目的的角色相同，因为“买方”并不总是与……相同的人。

当我写东西的时候--不管是文档还是其他东西--我收到的最好的建议就是总是假设你的读者是懒惰、愚蠢和刻薄的。简而言之，这意味着你应该总是为你最难读的读者写作，而不是为你最喜欢的读者写作。懒惰的读者不想从一大堆文本中筛选出答案，愚蠢的读者很难理解大词，而且刻薄的读者总是把模棱两可的措辞搞错。..。

文档通常分为两种不同类型的信息：描述性信息和基于任务的信息。描述性信息，顾名思义，描述的是什么。它通常用被动语态书写，用来围绕一个成分或主题提供上下文。另一方面，基于任务的信息描述了如何做某事。它通常是用主动语态写的，并引导读者执行一个或多个动作。这两种类型的信息都是必需的。

不准确的文档是毫无用处的。它不仅没有提供任何有用的信息，而且浪费时间，将用户送上错误的道路，并破坏了可能已经与他们建立的任何表面上的信任。除了确保文档可读之外，验证其准确性即使不是更重要，也同样重要。

为了确保文档的准确性，应该在整个过程中与原始功能开发人员进行一系列技术审查。第一次审查应该在编写任何文档之前进行，这样作者就有机会在动笔之前了解必要的信息。在写完初稿后，应该进行第二次审查，以验证所写文章的准确性。这确保了文档的编写.。

高质量文档的第三个，也是最后一个特征是可发现性。当涉及到文档时，如果用户找不到他们要查找的信息，那么文档的准确性或可读性如何都无关紧要。这可以通过几种方式来实现，每种方式都侧重于可发现性的不同方面。

建立直观和“可浏览”的信息体系结构是使文档可被发现的关键。在此做出努力是使读者能够找到所需的有关给定功能的信息所需的最低限度的努力。实现这一点的一种简单方法是建立一组基于主题的层次结构，将文档归类到以下项下：Dashboard&>Account&>Account Details。

除了建立信息体系结构以更好地组织文档之外，重点放在可用性上也很重要。在文档上下文中，可用性意味着在组织单页文档时考虑到易用性。代码片段中的语法突出显示、描述性动画GIF和“相关主题”部分等小事情可能会有很大帮助