在你告诉我我有多认真之前，请先听我说。
在过去的几周里，我阅读了几篇关于从软件开发人员的角度编写好的用户文档的文章。阅读多年来编写的文档的人经常告诉我这是一个专业领域。然而，当我离开 WordPress 十多年后，我几乎完全停止编写用户文档。似乎很少有用户注意到或质疑为什么没有针对某些功能的分步说明。
像许多 WordPress 插件和主题开发人员一样，我坚信手头有文档。作为自 2003 年以来一直在摆弄代码的人，文档一直是我最好的朋友。在我的整个职业生涯中，我至少编写了数百篇教程或文档页。我出版了两本开发书籍，第三本作为技术编辑出版。我可以有把握地说，我创建的一两个插件的内联文档多于实际代码。
不过，我也为最终用户提供了十多年的支持。我肯定了解到的一件事是，许多用户根本不阅读文档。即使他们正在阅读，大多数时候他们也不需要阅读。
尽管在每个问题到达支持论坛之前反复尝试、重新设计并尽一切努力让用户可以访问文档，但每天重复出现的问题都不会失败。
我花了数年时间 - 比应该的时间长得多 - 才意识到解决方案不在文档中，问题不在于用户可读性。问题是产品。如果用户问重复的问题，则意味着用户体验有问题。最后，我转移了注意力。我没有写更多的文档，而是专注于解决软件中不断出现的问题。
我失败的活动是听力。
开发人员可以获得的最佳技能之一是能够倾听用户的意见，然后将其转化为更好的代码、UI 和 UX。
当我年轻的时候——我怀疑许多开发者都是以同样的方式开始的——我觉得我知道每个问题的答案并且总是正确的。我很熟练，我知道。对于一个 20 多岁的年轻开发者来说，这往往意味着麻烦。这意味着您认为问题不在于您构建的内容。不，问题是用户做错了什么。这些类型的开发人员会说“RTFM”并向用户指出无法解决他们问题的过度技术文档。
有些教训是很难学到的，但是要学到它们，我们必须做出更好的产品。
我保证，如果您要对用户进行一项活动（倾听，真正地倾听），您将花费更少的时间来解释某事的工作原理。您需要问自己的问题是，为什么文档首先需要存在。如果需要 500 个单词来解释一项功能，那么该功能很可能不会带来理想的用户体验。
在构建产品时，我们应该始终努力构建它们，以便不需要文档。或者，至少构建它们，以便阅读手册是解决问题的最后手段。
出于实用目的，作为过去的全职开发人员，我保留了一个包含重复问题列表的简单文本文件。对于团队，这可能是一个更复杂的设置，例如创建 GitHub 问题。我的文本文件工作正常，因为我是一个人的表演。我养成了例行检查清单并询问我将如何改进每个领域的习惯。有些项目永远不会从列表中划掉。然而，我经常学习关于首先为最终用户构建的重要课程。我可以看到在我看来有意义但让其他人感到困惑的事情。
最大的进步不是找到现有问题的解决方案，而是根据过去的经验发现我正在开发的新产品中的问题。
随着时间的推移，我的大部分文档都面向开发人员。这些主要是关于使用 API、挂钩和其他与开发人员相关的功能的教程——这些不会由插件 UI 公开。当我根据他们的反馈和问题更新项目时，我为最终用户写的文章要少得多。是的，我有时确实会失败，但我会更好地成为一个根据用户自己告诉我的内容倾听问题和变化的人。
当我说最好的文档不是文档时，我并不是说您应该完全跳过它。我想问一个关于为什么需要文档的问题。您可以做些什么来简化用户体验？您是否在积极跟踪支持问题并解决产品本身的问题？
在开发中，我们经常谈到编写“自文档化代码”。这是一种编写代码的方式，您不必通过内联文档向其他开发人员解释它。例如，WordPress 中的 wp_insert_post() 函数告诉您它的目的是插入帖子。任何软件的目标还应该是创建自文档化界面和其他用户交互元素。用户应该能够在不查阅文档的情况下自动理解按钮、文本字段或复选框的用途。
下次您坐下来编写新的面向用户的文档时，请确保您没有将其用作糟糕用户体验的拐杖。
喜欢这样：
喜欢正在加载...
资源
