如何写出好的产品帮助文档？

Baklib

+ 关注

2022-03-23 18:32

415次阅读

如今，大多数软件产品通过互联网为用户提供服务，在线文档是最有效的客户服务渠道，我们熟悉的开源软件都配备了高质量的在线文档。

好的文档是优秀产品的标准配置，它不仅可以帮助你带来更多的用户，还可以帮助你为更多的用户服务。作为一名互联网程序员，如果你不知道如何写一份好的技术文档，你会不好意思向别人打招呼，更不用说制作好的产品了。

好文档的评价标准

“不知道从何开始，找不到好的角度写，写什么内容等等”，这都是我们经常会遇到的情况，那么为什么会发生这种情况呢？通常没有找到写作的意义，如果它是为了交换差异，头很容易卡住，思想无法扩展。

所以在敲击键盘之前，我们必须弄清楚这个文档是谁写的，以及通过这个文档可以帮助读者解决什么问题。写作是我们输出影响力的一种能力，它的最终目的是改变读者的信息、行为或信仰，否则它将是一个无用的垃圾。在明确了目标读者和意义之后，我们的想法就会被打开。

在编写文档的过程中会遇到哪些常见问题？

通常我们习惯于详细介绍产品的特点，具体如何安装、配置和使用等，事实上，大多数潜在用户是第一次接触这些产品，他没有完全了解我们的产品，不知道产品能帮助他解决什么问题，对他有什么价值，深入细节很容易让潜在用户。

说一个小故事，我记得研究生毕业后准备防御幻灯片。导师教我们一些经验：方御是向评委展示他们的研究成果，改变评委对这个研究项目的认知，并对自己的印象，以获得更高的分数。幻灯片最好从Why开始，告诉评委这个研究项目的背景和意义。有了这个基础，评委可能会对你的研究感兴趣，并跟随你了解一下What和How。

非功能特性依赖于功能特性。一个对用户毫无价值的产品，即使它的非功能特性非常优秀，也不会引起用户的兴趣。

文档的开头必须通过介绍产品或方案的价值与用户建立联系，让他知道产品或方案与他的工作密切相关，这可以帮助他优化工作。接下来是让用户知道什么是产品或方案，以及如何使用它。这实际上类似于软件研发的过程。从用户需求开始，首先分析和梳理用户的痛点，然后设计产品来解决用户的痛点，最后进行开发和实现。

文档目录设计和用户思维

当我们明确了文档的目标读者和可以为读者解决的问题时，写作本身就有了方向和价值，这样我们就可以调动我们的身心和大脑，让我们的文本思维涌动，这就是用户的思维。在此基础上，我们可以开始考虑文档应该包含什么，如何安排和设计目录章节，以更符合用户的学习规则。

文档是我们的外部输出产品，做产品学习同理心，从用户的角度考虑他们需要什么样的产品或方案，用户在技术选择中也首先确认产品或方案是否有价值，等他认识到价值将进一步了解产品或方案的功能特点和使用方法。

如何帮助用户获得控制感或安全感？

全景视图

全景视图，让用户有上帝的视角，从整体上把握产品或方案，这个视图不会包含太多的细节。就像穿过热带雨林到达一个地方，如果一端进入森林，那么我们很容易迷路，最好爬上高地或树冠，观察整个森林，包括河流方向和地标特征，掌握这些信息后我们会更安全，更确定走出森林。

全景视图就像一个装载信息的框架。我们应该首先帮助用户建立这个框架，然后向用户介绍详细的信息。此时，用户可以将其存储在框架的不同位置，因此他不会轻易迷路。因此，文档的第一部分是产品概述，包括背景描述、功能定位和优势比较。

构建演示环境

在对该产品有了全面的了解后，应用程序架构师的角色将构建一个演示环境，以便对该产品有更感性的了解。在这个阶段，他不需要对各种细节有特别全面或深入的了解，只需要知道如何以最简单、最快的方式配置它，他可以在这个环境的帮助下向团队中的开发测试人员介绍该产品。因此，文档的第二部分是快速介绍，主要是帮助应用程序架构师将对概念理论的理解转化为一个真实的演示环境。

介绍产品特性的开发指南

通过以上两部分，我们让用户知道该产品可以帮助他解决什么问题，以及它是如何工作的。接下来，将介入用户的开发、测试工程师和其他角色。他们需要深入了解产品的功能特性和使用方法，以指导具体的编码实现。

因此，文档的第三部分是介绍产品特性的开发指南。不同角色的用户对文档有不同的需求，文档章节目录的设计应符合上述顺序。

监控微服务

第四部分，除了知道如何使用本产品外，用户还将关心如何在日常使用过程中操作和维护，是否有一些配套工具或管理控制台，借助其监控微服务的运行，以及微服务的控制和治理。

梳理常见问题

第五部分，如何处理使用过程中遇到的问题，特别是一些非常频繁的问题，这部分将梳理这些常见问题，方便用户在遇到问题时咨询。