使用技巧

最好的文件就是没有文件

最好的文档就是没有文档最好的文档就是没有文档

在告诉我我有多严重之前,请先听我说。

在过去的几周中,我从软件开发人员的角度阅读了几篇有关编写良好的用户文档的文章。 阅读这些年来写的文档的人经常告诉我这是一个擅长的领域。 但是,当我离开WordPress十多年的时候,我几乎完全停止了编写用户文档的工作。 似乎很少有用户注意到或质疑为什么没有某些功能的逐步说明。

像许多WordPress插件和主题开发人员一样,我坚信手头有文件。 作为自2003年以来一直在摆弄代码的人,文档一直是我最好的朋友。 在我的整个职业生涯中,我至少写了几百篇教程或文档页面。 我出版了两本开发书籍,第三本是技术编辑。 我可以肯定地说,我创建了一个或两个插件,其内联文档比实际代码多。

但是,我也为最终用户提供了十多年的支持。 我可以肯定地了解到的一件事是,许多用户根本不阅读文档。 即使他们正在阅读,大多数时候也不需要。

尽管反复尝试,重新设计并尽一切努力使用户在进入每个问题的支持论坛之前都可以找到文档,但每天重复出现的问题都不会失败。

我花了好几年的时间-远远超出了应有的时间-才知道解决方案不在文档中,问题不在于用户的阅读能力。 问题是产品。 如果用户问的是重复问题,则意味着用户体验出了点问题。 最终,我转移了注意力。 我没有写更多的文档,而是专注于解决软件中不断出现的问题。

我失败的活动是倾听。

开发人员可以获得的最佳技能之一就是能够听取用户所说的内容,然后将其转换为更好的代码,用户界面和用户体验的能力。

在我年轻的时候-我怀疑很多开发人员在开始时都是一样的-我觉得我知道每个问题的答案并且总是正确的。 我非常熟练,而且我知道。 对于一个20岁左右的年轻开发者而言,这往往意味着麻烦。 这意味着您认为问题不在于所构建的东西。 不,问题在于用户做错了什么。 这些类型的开发人员会说“ RTFM”,并向用户指出无法解决其问题的过度技术文档。

有些经验教训是很难学的,但要学习这些经验,我们必须制造出更好的产品。

我保证,如果您要对用户进行一项活动(听,真正听),您将花费更少的时间来解释某项工作的原理。 您需要问自己的问题是,为什么首先需要存在一个文档。 如果用500个单词来解释一项功能,则很有可能该功能无法带来理想的用户体验。

在构建产品时,我们应始终努力构建它们,以便不需要文档。 或者,至少要构建它们,以便阅读手册是解决问题的最后手段。

出于实际目的,作为过去的全职开发人员,我保留了一个简单的文本文件,其中包含重复的问题列表。 对于团队来说,这可能是更复杂的设置,例如创建GitHub问题。 我的文本文件运行良好,因为我是一个单人表演。 我会养成例行检查清单的习惯,并问我如何改进每个方面。 有些物品从未从清单上划掉。 但是,我常常会从中学到关于首先为最终用户进行构建的重要课程。 我可以看到脑海中有意义但又使他人困惑的事物。

最大的改进不是寻找现有问题的解决方案,而是根据过去的经验来识别我正在开发的新产品中的问题。

随着时间的流逝,我的大部分文档都面向开发人员。 这些主要是关于使用API​​,挂钩和其他与开发人员相关的功能的教程-插件UI并未公开这些内容。 我为最终用户编写的文章少得多,因为我根据他们的反馈和问题来更新项目。 是的,我有时会绝对失败,但是作为一个能够听取问题并根据用户自己告诉我的方式进行更改的人,我会变得更好。

当我说最好的文档不是文档时,我并不是说您应该完全跳过它。 我想问一个关于为什么需要文档的问题。 您可以采取哪些措施来简化用户体验? 您是否在积极跟踪支持问题并解决产品本身中的问题?

在开发中,我们经常谈论编写“自文档代码”。 这是一种写代码的方式,您不必通过内联文档向其他开发人员解释代码。 例如,WordPress中的wp_insert_post()函数告诉您其目的是插入帖子。 任何软件的目标还应该是创建自文档界面和用户交互的其他元素。 用户应该能够自动理解按钮,文本字段或复选框的用途,而无需查阅文档。

下次坐下来编写新的面向用户的文档时,请确保您不会将其用作支撑不良用户体验的拐杖。

像这样:

喜欢加载中……

资源