编写好的文档入门

已发表: 2015-06-06

这篇文章是由客座作者 Jeff Matson 贡献的。 Jeff 是 GravityForms 的文档负责人。他是 Heartbeat Control WordPress 插件的创建者，是 90 年代的粉丝。

通常，文档是开发过程中最被低估的部分。当我们查看 WordPress 社区中的摇滚明星时，我们通常会查看开发人员、设计师和营销人员。对于那些为确保一切顺利进行而流血、汗水和眼泪的文档编写者知之甚少。

这篇文章是关于那些日复一日地盯着没完没了的代码行来破译开发人员的想法的人，以及存在的代码背后的真正含义。

好的文档不仅仅是文字

优秀的文档编写者提供的不仅仅是指导手册，他们还提供了一种体验。我认识优秀的记录者，指导过的初学者，他们之间最大的区别是了解阅读者的大脑。就像小说一样，文档有一个流程，可以让读者保持兴趣并吸收比他们意识到的更多的信息。

质量文档针对最有可能阅读它的用户。它还为那些不太可能阅读它的人提供了一个参考点。例如，如果记录一个特定的钩子，通常假设开发人员会阅读它，但是那些没有开发经验的人呢？

一个好的文档编写者将为那些需要更多推动正确方向的人提供参考点，而无需联系支持人员为他们详细说明。

大多数人只是简单地忽略文档，将其推入无尽的深渊，直到他们再也无法忍受。在某些情况下，我也犯了同样的罪。这些人没有意识到，每当他们的插件或主题未记录在案时，用户体验就会受到影响。

让我们来看看您最常见的支持票。如果你能更好地记录这个问题，这些票会完全消失吗？可能不是。您是否会减少有关该问题的票证并提高您或您的支持代理的工作效率？我保证。我认为我们都可以使用更少的支持票。

正如我之前提到的，文档对用户体验产生了巨大的影响。如果用户能够轻松有效地找到信息，他们就节省了自己和您的时间。世界平均预期寿命为 66.57 岁，您的用户宁愿在生活中做点别的事情，也不愿摆弄写得不好的文档。

如果客户看到您在文档中投入了相当多的时间和精力，那么无论是否有意识，他们都会更加感激您。良好的文档表明您在首次销售后关心他们。

您是否曾经在花掉血汗钱后感到高高在上，很快就后悔购买了？我想我们都有。通过适当的文档，您可以避免将这种感觉传递给您的客户。

第一步是停止避免它。一旦你擅长它，编写文档比你想象的更愉快。事实上，它将成为第二天性。就像世界上的其他事物一样，熟能生巧。

在决定将文档提升到一个新的水平时，您首先要采取的步骤之一就是确定您的痛点。你在联系什么？如果你开始盲目地写东西，你可能会发现你写的东西并没有产生你想要的影响。

我发现的最佳技术之一是跟踪记录的票证数量与未记录的票证数量，并将未记录的票证分类。这样，您可以更好地针对您的痛点，并修改可能没有应有的帮助的部分。

在确定了应该编写的文档之后，您应该确定目标受众，并将其分解为开发人员、用户和高级用户。这可以帮助您迎合特定的受众。稍后我们将讨论如何定位这些用户。

接下来，您要分解文档。对于开发人员，您需要将其分解为原始信息（接受的参数、返回值等）、特定示例和用例。对于用户来说，最好的做法是演练。他们需要采取的每一步，无论看起来多么微不足道，都是至关重要的。

在每一步都向他们说明。为高级用户编写文档与用户场景非常相似，但更具结构化和可扫描性。要清楚，但要让他们轻松跳到他们需要去的地方，而无需先阅读上一步。

当谈到编写文档的艺术时，请以最适合您的受众的方式编写，但也要使用您知道他们会理解的简单语言。最好的原因之一是翻译。虽然谷歌翻译做得很好，但翻译五年级学生的简单词汇比翻译研究生论文中的词汇要容易得多。

在您的内容中，不要害怕链接到相关内容。这将使您避免重复阅读多个文档，并允许读者在需要有关特定主题的更多信息时回溯。毕竟，您的主要目标是让用户满意，并节省自己的时间。

按下发布按钮后，文档过程不会停止。返回并根据需要修改每个文档。几乎在文档发布后立即返回并查看您跟踪的支持票是否下降，以及该特定文章的访问量是否增加。通常，如果您的文章获得更多访问量，这会有所帮助。如果您获得更多流量但支持票证数量相同，您可能需要查看该文章以了解原因。

首先，我希望在做到这一点之后，您对那些在战壕中编写我们大多数人认为理所当然的文档的人有更好的理解。它确实是一种艺术形式，我们中的许多以编写文档为生的人真正享受并投入了很多很多时间。

我也希望您从这篇文章中走出来，更多地思考您现有的文档以及如何改进它。正确的文档可能会非常有益，并且一旦在实践中，编写起来实际上会很有趣。

尽早记录，经常记录。一个伟大的产品不仅仅是伟大的代码，它也有精美的文档。