为什么科技产品的文档很难使用？ （从用户的角度来看）

如今，我们的开发人员工具文档很难使用，我们倾向于在其他来源（例如 Youtube、GitHub 问题或博客文章）上找到解决方案。它的内容可能很容易落后，或者根本没有提到重点。我认为这个问题是一个紧急问题，我们应该尽快切换，我认为首先需要解决两个主要问题。 （站在用户的角度）

• 文档太难贡献
  • 文档很容易过时。人们倾向于撰写博客文章而不是为文档做出贡献，因为这需要大量额外的努力而没有相应的激励措施。
• 上下文是聚集的

  • 文档本身几乎不与其他资源相关联。制作好的文档的上下文是聚集的。

    
    

在本文中，我想围绕文档介绍两个我认为有问题的概念，然后将其进一步扩展为解决这两个问题的 3 个思考点。

首先，请回忆一下您最近访问过的一些文档，并与我一起解释以下内容。我想以 Next.js 为例，这是我目前访问量最大的文档。让我们从“入门”页面开始。

https://nextjs.org/docs/getting-started

Nextjs 的文档有一个通过各种产品流行的结构，我把这种结构称为“隔离列表结构”。我称它们为孤立的原因是它们主要由 Next.js 背后的人维护（尽管它们是开源的）。

此外，我想将本文档背后的心态总结为“所有者的要点”。

业主要点

我称之为“所有者的要点”的原因是生成文档的过程通常由产品所有者完成。在一个产品的开始，没有人比所有者更了解。所有者是为其消费者和维护者维护适当文档的最佳人选。

但过了一段时间，该产品受到了很多人的喜爱，并开始建立社区。跟进极端案例和错误变得越来越困难。所有者必须每天赶上新的提交并解决问题，另一方面，他们必须解释新的设计和警告并为新人提供信息以克服这些问题。负载急剧上升。

不是每个产品都能赶上，内容开始落后，一些解决方案可能存在于别人的博文、StackOverflow 的答案、GitHub 问题或讨论中。用户需要将这些解决方案与搜索引擎联系起来，有时文档上的解决方案甚至是错误的。

孤立的上市结构

孤立的列表结构在电子商务、通用网站、手机和文档中非常常见。它无处不在。

由于业主必须首先按照他们认为最适合其客户的顺序提出结构树，因此该结构大多是任意和固执的，来自“业主的要点”的心态。

孤立的上市结构是一把双刃剑：需要明确的是，我并不完全反对这种结构，它在一般情况下确实很有帮助。例如，它有利于初步探索，如果您熟悉该文档，则很容易找到您想要的信息。

但另一方面，它是一个固定的结构，结构很难进化，每次维护者想要添加其他东西时，如果所有者一开始就没有考虑好，很难找到合适的地方。除此之外，用户别无选择，只能浏览您的文档。他们只有一条路线，而且还不够。

想象一个动态结构，比如一个力导向图（像 Obsidian 可以完成的东西或树图，你可以在他们的发布部分找到很多例子[^1]）。我并不是说力导向图或树状图比孤立的列表结构更好。我想要的是鼓励大家不要用“列表的方式”思考，而是用更“动态的方式”思考，这样人们就可以选择最适合自己需求的东西。他们可以使用树形图来探索结构，并使用力导向图来确认主题之间的联系。或者我们可以从头开始设计一个新的结构来解决其中的一些问题。

结合起来，心态和结构导致了我认为有问题的问题，如下所列。

文档太难贡献

结合“所有者子弹点”和“孤立列表结构”的任意心态，我们所拥有的是当前文档只能由所有者正确维护，没有其他简单的方法可以为文档做出贡献。问题是双重的。

首先，基于“所有者的要点”的心态，作者不希望一些没有经验的人弄乱你的文档，如果你不花很多时间与维护者保持一致，就很难匹配文档的基调。

其次，您的用户没有任何动机为文档做出贡献，人们喜欢您的产品，但是如果他们在文档的构建中没有获得任何信用或对某些文档页面的所有权，那么就没有动力。

您可能会争辩说他们可以发布问题并解释他们的建议，但问题仍然存在。贡献的感觉是同时发生的，就像买东西的感觉。想象一个平行世界，在这里，如果你想买东西，你需要写下 200 字来描述你为什么要买这个东西，以及对社区有什么好处。

没有必要通过官僚机构来阻止人们提供文档。我们需要提出另一种结构，既能保持文档的权威性，又能同时受益于同步贡献。

上下文是聚集的

好的文档的素材不仅仅是文档本身，还有相应的讨论、问题、相关的博文、视频。我将这些材料称为“上下文”。

直到最近，我们还倾向于分布式存储这些上下文。一个常规的开源项目将他们的讨论存储在 GitHub 讨论或讨论论坛中，他们的用例存储在产品网站中，问题直接存储在 GitHub 问题中，以及其他地方的自托管文档网站。除此之外，YouTube 和个人博客帖子上还有很多社区生成的内容。

实际上，产品的上下文变得集群化。它们之间不会有相互联系。可能会讨论特定错误的解决方案，但在文档部分中没有提到此解决方案的反向链接。可悲的是，我们必须面对这样一个现实，即双向链接不是当前互联网所能提供的。

集群上下文是易变的

想象一下这样一种情况，当您查看产品的文档并很快发现文档没有提供解决方案时，您在其他人的博客文章中找到了可行的解决方案。

目前，以目前的文档，没有其他方法可以提醒其他开发者，他们可以用博文描述的这种方法解决同样的问题，不能在文档中添加参考。您可以做的是打开一个问题（如果它是开源的）或在论坛上打开一个讨论，以提醒人们这个解决方案很快就会被其他内容淹没。

在任何情况下，每个有用的解决方案都需要抵抗我们现在拥有的大量信息。他们必须加入这个战场，除了搜索引擎之外没有任何锚点。

很棒的列表 [^2] 是个好主意，它们提供了一种让优质内容保留下来的方法，但是它们在“孤立的列表结构”和“所有者的要点”思维方式方面存在相同的问题。

如果情况保持不变……

这些问题的直接后果将是“文档”将随着时间的推移而衰减。你可以看看一些科技巨头的文档，包括亚马逊网络服务文档或谷歌云文档，它们都是压倒性的，难以阅读。

最糟糕的感觉是您被困在文档和其他任何地方都找不到的特定问题上。如果我们的文档结构与我们使用的产品范围不一致，我们将更多地面临这种情况。

首先提出一种新的结构来克服这些问题似乎势不可挡。但仔细观察，我们可以将整体问题分成 3 个问题来问自己。

• 如何鼓励用户为文档做出贡献而不干扰文档的通用性？我们能否为文档提供更具交互性的体验？用户可以在不离开页面的情况下直接为文档做出贡献吗？

• 如何将上下文收集在一起以获得更好的搜索体验，而不依赖外部搜索解决方案，并在此过程中实现每个上下文的互连？

• 如何尝试一种可能有益于用户体验的新结构并随着时间的推移对其进行迭代，甚至让用户自由选择？

  
  

https://twitter.com/EiffelFly

[^1]：黑曜石发布页面[^2]： sindresorhus/awesome