WordPress 专业人士的产品文档

已发表: 2017-07-28

产品文档通常被视为无关紧要的，您可以偷工减料。它不被视为可以为客户提供价值的东西，也不被视为可能影响收入和营销等关键业务领域的东西。当然，作为 WordPress 专业人士，您不需要像 Atlassian 或 Cisco 那样编写文档。通常，当人们想到“文档”时，他们会联想到厚厚的印刷用户指南图像，这些图像按字母顺序排列在一个没有人阅读的非常大的书架上。

但这已经改变：

随着敏捷和 DevOps 的出现，发布软件变得更快，开发周期也变得更加动态。因此，文档现在反映了最新版本的当前状态，而不是永远写在纸上的静态内容。文档被集成到开发周期中，并且与软件一样频繁地更新。

为什么 WordPress 专业人士应该关心产品文档？

有用的最新文档不仅使用户的生活更轻松，而且还增加了一定程度的润色，成为独一无二的营销资产。相反，糟糕的文档会产生负面影响。您可能自己也经历过：您遇到了一个问题，您正在努力在文档中找到解决方案，而当您没有找到解决方案时，您最终感到沮丧（并且可能很生气）。如果您为产品付款，情况只会变得更糟。

如果您在 WordPress 代理机构工作，在项目的所有领域（从初始设计到资产）交付文档，将增加一定程度的专业性，表明：

你注重细节。
你关心你的客户，足以加倍努力。
您对自己的设计和技术项目决策保持透明和自信。

MindTouch 营销副总裁 Mike Puterbaugh 写了一篇 Mashable 文章，描述了您的产品文档是营销资产的 5 个原因。他总结如下：

这不是一项性感的事业，但它会让你赢得同行的尊重、更有效的公司管理和更协作的团队。因为这不是关于本季度或今年，而是关于影响竞争优势和长期增长。

现在我们已经建立了足够的动力，我们将：

探索与 WordPress 相关的不同类型的产品文档。
讨论每种文档类型的需求并提供可行的建议。
就如何规划和协作处理产品文档提供一些初步指导。特别是如果您在 WordPress 代理机构工作。

WordPress产品文档的类型

WordPress 产品不仅仅是关于插件和主题。在本节中，我们还将讨论在线帮助、REST API 和一种叫做微内容的奇怪事物。

WordPress插件

WordPress 插件文档需要迎合两类人群：用户和开发人员。每个人的文档需求都不同，使用的写作风格也不同。

用户

用户的文档需求主要围绕故障排除和配置。除此之外，您需要以有吸引力的方式展示您的插件，以便让用户试用。每个插件在 WordPress 插件市场都有自己的页面。请记住以下几点：

写一个引人入胜且有用的描述，鼓励下载和使用。
从您的仪表板插件配置页面添加带有说明的带注释的屏幕截图。
在常见问题解答中提出有用而不是陈词滥调的问题。
拥有更新且编写良好的变更日志。不要在那里添加神秘或简洁的注释。

您应该记住，当用户使用文档时，他们可能急于寻找解决方案。写清楚，简单，简洁。不要让他们比现在更难。

开发者

除了遵循最佳软件实践和官方 PHP 编码标准外，您还应将注意力集中在以下方面：

插件钩子

这些完成了修改 WordPress 行为的工作。很可能您的 WordPress 插件使用了这些。由于插件挂钩是代码的重要组成部分，因此您应该记录如何使用它们以及它们涉及的 WordPress 功能。

模板标签

模板标签是 WordPress 插件增强功能的另一种方式。记录您编写的模板标记函数。包括有关其他用户或开发人员如何在其 WordPress 网站上使用标签的示例。

选项

选项是一种在 WordPress 数据库中存储特定信息的方法。这是通过 add_option 和 get_options 函数完成的。在这种情况下，记录您传递给这些函数的参数。

数据库

插件经常从数据库中读取和写入许多不同的东西。由于这些是基本操作，因此记录它们将极大地帮助其他开发人员了解您的插件是如何工作的。

WordPress 主题

您可以在两个不同的区域为主题创建文档。首先是源文件。带注释的 CSS 文件比没有注释的 CSS 文件更容易理解和阅读。使用诸如 css_doc 之类的工具来帮助您。这会生成 JavaDoc 样式的文档，并且可以发布：

另一个领域是风格指南。这些文档描述了元素的外观以及在什么情况下需要使用它们。它们强制一致性并使协作更容易。您可以阅读 Hubspot 的 20 个令人惊叹的品牌风格指南示例文章，因为它包含许多很棒的示例。

同样，不要忘记查阅官方的 WordPress CSS 编码标准。

如果您是 WordPress 代理商，那么详细记录设计元素也有助于新员工的入职。样式指南可用作新的和过去的客户工作的教程或参考材料。

网上帮助

由于在线帮助旨在解决特定的用户问题，因此从常见任务和问题列表开始是可行的方法。尽管最初的清单并不详尽，但请花时间制作尽可能多的具体项目。这个想法是为这些任务和问题中的每一个编写一个在线帮助文件，并将它们超链接到相关信息。您可以创建用户旅程来规划用户在您的应用程序中可以采取和执行的不同路径。深入研究支持电子邮件以注意常见问题和有问题的领域是使您的知识库保持最新和有用的好方法。

Barry J. Rosenberg，Spring into Technical Writing 一书的作者提供了以下建议，以便编写好的帮助文件：

使每个帮助文件尽可能简短。喜欢编号列表而不是项目符号列表。不要离题，不要脚注，不要随意。让每个帮助文件专注于单个离散任务。

微量内容

微内容有两个定义：第一个是用户浏览的标题和部分等内容，以便了解特定文章的要点。第二是可以独立存在并用于增强用户体验的小内容。我们想到的一个特别好的例子是 Slack 的“几个人正在打字……”位。（尽管 Slack 充满了优秀的微内容）。

当超过 3 个人同时在同一个频道中输入时，就会触发该位。 Slack 不仅打印了当前正在输入的人员列表，还获取了这条无聊的信息并为其添加了一些乐趣。讨论开始变得非常激烈，它表明了这一点。这是一个很好的例子，说明产品文档（应用程序消息是其中的一部分，不是吗？）让人们谈论你（并创建像上面这样的搞笑模因）。

REST API

记录 REST API 本身就是一门独立的艺术。与所有技术写作一样，您应该以定义简洁、清晰和简单为目标。由于 REST API 有自己的格式和复杂性，因此您最好学习一下 Tom Johnson 在他的 Id rather Be Writing 博客上编写的优秀的 API 文档指南。

协作和规划文档

最终，文档应该成为产品设计的一部分。因此，您应该将其视为在您的软件周期中有一个额外的管道。这意味着使用软件存储库来存储最新的文档版本，使用错误/问题跟踪器来监控任务和问题，将文档项目规划纳入您的路线图，最后但并非最不重要的是，与其他人协作。如何开始的大致轮廓如下：

记录用户想知道的所有内容，以及您需要为其编写文本的区域。
拥有所有内容后，将它们按类别分组并形成文档标题。
为每个文档写一个规范，详细说明诸如标题、描述、目标受众、媒体（文档将具有什么形式）、长度、需要多长时间等。
将文档规范中的估计添加到您的项目计划中。

由于产品文档涉及所有领域，因此几乎可以肯定您需要与组织内的不同人员一起工作。坐下来就所有这一切将如何进行的某种过程达成一致是个好主意。与每个项目一样，您应该确定将提供技术援助的利益相关者，以及将审查和编辑更改的利益相关者。

这个过程应该有不同的阶段。这些应标出信息的收集地点、文档的编写时间、文学校对的准备时间、技术评论的时间、出版时间等。强调文学、技术和与内容相关的评论之间的区别。例如，当您要求团队负责人对您的文档发表评论时，它并没有真正有用，而不是技术相关的信息，您需要语法和标点符号。

结束

产品文档是一种可以长期获得回报的资产。它为您的客户带来价值。它甚至可能非常好，例如 Stripe 的 API 文档，以至于人们在论坛上对它赞不绝口。这可以建立参与度并以自然而有力的方式宣传您的品牌和产品。当与创意微内容相结合时，它实现了 Mike Puterbaugh 所说的产品文档是“营销的秘密武器”的意思。