以产品思维方式编写更好的文档

以产品思维方式编写更好的文档
经常看到在产品管理和用户体验设计环境中讨论产品思维，但还没有看到它应用于技术写作和文档。然而，通过将产品思维应用于文档，我们可以编写更有用、相关、高质量的文档。 

什么是产品思维？ 
产品管理思想领袖Shreyas Doshi 在 Twitter 线程中对产品思维的定义如下：
“产品思维是关于理解动机、构思解决方案、模拟它们的效果，并根据你想要创造的效果选择一条路径。”

作为一名技术作家，我将关注用户问题和客户旅程作为我工作的核心部分，因此将产品思维用于文档似乎是显而易见的。

当我在 Splunk 工作时，文档文化培养了一种产品思维方式，这种思维方式体现在 Splunk 文档书籍The Product is Docs中。
尽管沉浸在那种文化中并且非常关心帮助用户，我仍然发现很容易陷入“完成它”的心态，或者 Doshi 所说的项目思维： 
“项目思维是关于理解期望、制定计划、整合资源和协调行动以满足这些期望。”

项目思维侧重于创建产品的步骤和过程，而产品思维侧重于创建产品的动机以及该动机的可能结果。

为什么项目思维在技术写作中无处不在 
技术作家通常缺乏时间和资源。被迫跟踪多个团队和项目，我们经常将尽可能多的精力花在看起来最紧迫的优先事项上。即使有足够的资源和计划，时间紧迫仍然会发生。有了这些限制，很容易只专注于编写文档并跟上进度。

与工程师一起冲刺，我们经常采用工程实践，例如将我们的工作分解成小部分，写票并将它们添加到冲刺中以与开发人员一起跟踪。随着 CI/CD 管道在产品开发中的广泛采用，这些实践进一步渗透到我们的文档流程中。 

从“功能覆盖率”的角度考虑文档项目，感觉就像是一种优化捷径，就像如何根据“测试覆盖率”考虑质量保证项目一样。文档可以成为另一个需要勾选的框，确保部署的每个拉取请求都具有足够的产品功能测试覆盖率和文档覆盖率。 
这种“覆盖”的心态是由项目思维支配的。如果我们采用产品思维方法会怎样？

项目思维与产品思维
虽然项目思维引导我们编写确保覆盖特定产品功能的文档，但产品思维帮助我们专注于需要编写的内容和原因。拥抱产品思维让我们可以编写与客户更相关的更高质量的文档。

这可能看起来好得令人难以置信，所以让我们看一个具体的例子——一个产品对开发人员可用的 API 端点进行更改，作为版本更改的一部分。

记录API 端点弃用情况的项目思考
对文档采用项目思维方法可能如下所示： 

• 记录每个新端点
• 确保每个已弃用的端点都有指向相关新端点的链接

项目中可能还有一个弃用计划，其中包括“向旧端点添加横幅，并带有指向新端点的链接，表明它们已被弃用并将在未来被删除”。  

作为项目思考者，这种方法具有以下要素：

• 期望：记录新的 API
• 计划：文档和工程协同工作以生成更新的文档向用户提供弃用信息
• 资源：文档和工程
• 交付输出：新 API 版本和共享弃用计划提供的文档

这种方法主要关注新功能的覆盖范围，并通过提醒用户注意更改来为使用旧功能的用户提供某种形式的连续性。 

API 端点弃用的产品思考
对文档采用产品思维方法可能会如下所示：

• 一旦您知道 API 端点将发生变化，请编写学习成果，例如以下示例：
  • 作为开发人员，在阅读 API 文档后，我可以成功更新我的代码以使用新的端点。
  • 作为一名开发人员，在阅读 API 文档后，我确信我不会丢失任何数据，并且可以正确处理新端点发送的数据格式。 
  • 作为开发人员，在阅读 API 文档后，我可以向正在度假的同事解释哪些端点发生了变化。 
  • 作为一名开发人员，当我需要部署我的新脚本时（当 API 更改成为永久性时），我想向我的老板解释。
• 记录每个新端点。
• 确保每个已弃用的端点都有指向迁移指南的链接。
• 为 v1 API 的用户编写指南以帮助他们迁移到 v2 API，该指南通过包括以下内容来解决您定义的特定学习成果：
  • 指出对数据格式进行任何更改的注释或警告。
  • 具体代码示例将使用已弃用端点的 API 调用与使用等效的新端点和参数的 API 调用进行比较。
  • 明确日期或通信方法，开发人员可以在其中找到 v1 API 何时停止工作。 

从产品思维的角度来看，这个步骤列表涵盖了要点：

• 动机：通过编写学习成果来识别客户动机
• 解决方案：列出解决客户动机的文档选项。
• 模拟：编写迁移指南并草拟特定代码示例，以通过工程和产品管理进行验证。
• 预期的结果：客户实现业务连续性，工程可以弃用旧的 API 端点并停止维护代码。 

这种方法主要关注客户结果，而不是针对生成特定类型的文档或可以检查计划的特定输出进行优化。 

比较结果
如果项目思维针对覆盖和输出进行优化，那么产品思维针对结果进行优化。
从产品思维方式编写的文档看起来要详细得多，但创建起来也很慢且资源密集，但产品思维只是在短期内缓慢。
如果您专注于覆盖范围（和输出）而不是结果（和客户成功），您可能拥有完整的文档，但它对客户没有那么有用。随着时间的推移，您可能不必担心很多这些问题。 

我并不主张完全放弃项目思维。我们不能忽视资源考虑或我们所写内容的内容交付时间，尤其是当我们作为单独的作家工作时。但是，正如考虑我们所写内容的时机至关重要一样，我们也需要考虑我们所写内容的有用性。

培养产品思维思维方式对于编写有用的文档至关重要。

将产品思维应用于文档
一般情况下很容易养成“反应性”纪录片的习惯，响应信息请求，并一页又一页地死记硬背地更新更多信息。
作为技术作家，我们的优先级列表经常变化或洗牌。那么，您如何将产品思维应用到您的文档中呢？ 像产品一样接近文档本身。

在您的写作过程中创建提示，与具有重要信息的人联系，为您的文档编写学习成果，考虑文档的内容设计，并测试有关您提议的更改的所有内容！

创建过程提示
为确保您不会在“完成写作”上花费太多时间，请在文档过程中添加提示，以帮助您在写作中保持以用户为中心。什么样的线索？这取决于你的写作方式，但这里有一些对我有用的：
遵循文档票的模板。在一个快节奏的开发项目中，我确保我提交的每张文档单都包括以下内容：

• 内容的受众
• 更了解该功能的技术型中小企业
• 内容的学习成果

如果我无法填写这些详细信息，我就知道如果不产生低质量的内容，我就无法处理文档请求。 

定期审查和计划您的工作。在另一个项目中，我通过在周五下午花一些时间回顾我在上周完成的工作并计划下一周的任务来接受项目思维的基本要素。通过识别与我计划处理的每个文档任务相关的关键产品结果或客户目标，我将一种以输出为中心的方法与以结果为导向的方法相结合。 

访问人员
如果您无法联系产品经理、工程师和客户来理解和验证这些结果，那么就不可能在编写以产品为中心的文档时考虑到客户结果。 
确保您可以与为您的产品工作的产品经理、工程师和 UX 设计师交谈，但尤其要采取措施与每天直接与客户互动的销售和客户支持代表建立关系。 

通过联系产品专家和客户专家，您可以更轻松地识别和验证推动特定产品功能开发的客户动机。这在敏捷开发环境中尤其重要，您正在记录的功能可能只是大型解决方案的一小部分构建块，但孤立地看它似乎笨重且损坏。例如，添加了存储有关事件信息的功能的事件管理功能，但忽略了表示事件状态的状态字段。

深入了解产品开发决策背后的原因和原因后，您可以以适应客户目标以及这些可能的产品限制的方式构建和编写内容。例如，您可以编写一个事件管理工作流，其中包括用于向事件添加状态的选项。通过这种方式，您正在编写解决现有功能、客户期望结果的文档，并为展示未来产品功能留出空间。 

写学习成果 
了解客户在使用产品时的期望结果至关重要。但是，作为产品的技术作者，您还希望在使用文档时确定客户的结果。 
当你写一个学习成果时，你想使用活跃的词并且是具体的。这些不是抽象的用户故事，而是客户可以实现的具体结果。 
不要这样写：

• 阅读文档后，我了解了如何调用 API。
• 阅读文档后，我了解了如何在产品中创建事件。

相反，请具体说明期望的客户结果：

• 阅读文档后，我可以成功更新我的代码以调用新的 API 端点
• 阅读文档后，我可以自信地根据 DevOps 的电话创建事件。 

您需要为您的文档编写特定的学习成果，以便您的文档也可以对客户具有特定性和有用性。 

如果你不能为某个功能写出令人信服且具体的学习成果，有几件事可能是正确的：

• 您可能不需要记录它。如果没有任何相关的客户结果，它可能不需要文档。
• 您可能还不够了解客户的动机。与产品管理人员和技术 SME 联系以了解该功能的原因，以深入了解为什么要将该功能添加到产品中，从而发现推动开发的动机。

为您制作的每份文档（包括小型文档）编写学习成果有助于将您转变为产品思维方式，并提醒您为什么您的文档很重要。 

考虑内容设计
产品思维方式的另一个要素是考虑新想法。内容创建可以让人感觉常规和直接，但它涉及设计和写作一样多。

考虑你写作的内容设计可以使你的写作更容易理解、更具包容性和更有用。如果您包含更多标题或将段落更改为表格或列表，则您的内容更容易扫描，因此对任何容易感到无聊、匆忙、阅读障碍和/或 ADD 的人更有帮助。

您还可以使用图表或屏幕截图等视觉效果来拆分段落，并使用有用的替代文字，这可以强化您的内容并为更多视觉学习者提供额外的学习机会。

除了调整文本的设计外，您还可以更改呈现内容的方式和位置。考虑以下文本文档的替代方案：

• 互动产品之旅
• 2-3分钟的视频
• 使用演示环境的交互式教程

例如，您可以写一篇博文，使用常见的 IT 事件或新闻中的安全漏洞来介绍产品中的事件管理功能。这种替代形式的内容在一篇过时的博客文章中为客户提供了一个切实相关的示例，您不必保持更新。

测试一切
要继续将文档视为产品，您需要测试您在此过程中做出的决定。验证您确定的产品动机、您定义的客户学习成果，并利用您可用的任何和所有测试选项。 

• 从技术 SME 那里获得有关您内容准确性的评论。
• 就您的内容呈现方式向同行征求反馈，尤其是在您尝试新事物时。 
• 如果您可以访问编辑器，请发送您的文章进行编辑。
• 使用Vale或类似工具检查你的写作风格指南的遵守和完成情况。我因发布带有断开链接和未完成句子的文档而感到内疚。自动或手动清单对于确保您的工作完成至关重要。
• 对内容执行 UX 测试。如果您重组了信息架构，请使用树测试来测试您所做更改的直观性。 

以产品思维方式编写更好的文档
凭借产品思维思维，您可以清楚地了解为什么要记录某些内容。最后，这种清晰的理解产生的文档为客户提供了宝贵的资源，甚至可以证明是与竞争对手的差异化因素。 

banq：以产品思维编写文档，实际就是多写写除了产品功能以外的上下文背景资料，目的、动机是什么。