桌面游戏能教给软件文档什么

你还记得大富翁、人生之旅和妙探寻凶，以及所有那些你小时候玩的经典桌游吗，因为有时候你就是那么无聊？你还记得曾经读过说明书吗？可能没有，因为没人会读那些游戏的说明书。我们都有一位朋友，他大概知道怎么玩游戏，所以他们教我们怎么玩，这就足够了。（说真的，回去重新阅读一下大富翁的说明书；我敢用互联网上的钱打赌，你从来没有按照实际规则玩过这个游戏。）

如果你真的尝试读过说明书，你会发现它们是在 1962 年写的，读起来几乎和通用电气冰箱的维修手册一模一样。它们同样详细、同样完整，也同样无趣。

这听起来是不是很熟悉？

再想想。这听起来是不是太熟悉了？嗯，应该的，因为这正是当今软件文档仍然存在的问题。

桌面游戏说明书

我永远不会忘记第一次购买现代桌游的情景。我打开盒子，深吸一口气。是时候读说明书了。

令我惊讶的是，说明书只写在半张纸上，字体很大，留白很多，还有三个很大的数字，配有宜家风格的插图，几乎是侮辱智商的程度。

1. 给每位玩家发五张牌。（五张牌手的图片，向读者展示他们在游戏中会遇到的不同类型的牌。）
2. 将一张任务牌放在桌子上，按照指示进行游戏。（任务牌样子的图片。）
3. 每回合出两张牌。按照牌上的指示去做。第一个完成最近打出的任务牌上所写内容的人获胜。

“你开始玩了！”

就是这样。这些是（为了这个例子而修改过的）说明书。三个步骤，以及一声响亮的呼喊，嘿，别看了，你已经在玩游戏了，而且你已经上手了。

公平地说，这三个步骤并没有涵盖很多细微之处。幸运的是，在“你开始玩了！”这句话之后，作者又偷偷地写了三个段落，提供了更多关于牌的类型、它们的含义等等的细节。

在最初的几局游戏中，我们有很多次不得不停止游戏，挠着头问：“等等，我们不能在那张牌之后出这张牌，对吧？现在会发生什么？” 为了找到答案，我们回到规则，查看规则表背面的小参考部分，在玩的过程中学习游戏的技巧。

但你看，它骗了我们；我们感觉不像是在读说明书，因为我们正在积极地玩游戏。我们不是在读说明书，严格来说；我们是在使用规则作为参考。它实际上是游戏的一部分。

让软件文档成为游戏的一部分

并非所有内容都适合三个步骤、三个后续段落和一个参考部分。但你会惊讶地发现，当你的目标是这样时，说明书会好得多。例如：

三个简单步骤

1. 给你的读者一个清晰的入口点。阅读用户指南的人想知道如何使用你的应用程序，而不是理解驱动你编写它的理念。
2. 列举用户必须做的事情。这是一种良好的床边服务；它不是绝对必要的，但它有助于用户准确理解你的应用程序对他们的期望。这是一个清单，让他们知道这些是接近这个应用程序时要采取的正确步骤。
3. 把你的用户放在一个跳板上，而不是一个充满尖刺的坑里。在你的枚举的“入门”列表之后，确保你的用户准备好进一步前进。这就是你的推销：看看入门有多容易！只需要三个步骤！现在你不想读接下来的三个段落，了解你可以从这里做什么很酷的事情吗？如果你的用户从你的三步介绍中下来，盯着一个空白屏幕，不知道接下来可能会发生什么，你需要重写你的文档，或者你可能需要重写应用程序。

就是这样！

是的，经常向你的用户宣布他们在你的文档中的位置。这可能看起来很屈尊，但你的读者不知道他们成为这个奇怪的新应用程序的专业人士的道路上的哪个位置。所以告诉他们。他们刚刚完成了你的应用程序 50% 的功能吗？或者他们所做的只是配置它，以便它将在他们的系统上启动？告诉他们。让他们知道。要清晰、诚实、兴奋。向他们保证，这一切都非常正常，并让他们了解正在发生的事情，例如他们是否应该每次坐下来使用应用程序时都执行这些步骤，或者这是否是一次性设置，他们永远不会再做。

沟通。

这就是所有的介绍应该做的。轻松、令人放心、肯定、让人自我感觉良好。你只是在向你的读者推销这样一个事实：你保证你的应用程序是平易近人的。他们可以做到这一点。

三个段落

在你向读者保证他们可以掌握这个应用程序并取得胜利之后，告诉他们接下来应该去哪里。他们是使用这个应用程序来构建小部件还是分析小部件？它可以两者兼顾，所以通往其中一条道路的路径在第 3 章，而通往另一条道路的路径在第 4 章。他们是在服务器上设置这个应用程序还是在本地使用？相应地转到第 5 章或第 6 章。等等。

后续部分的目的是警告你的读者，一旦他们真正开始工作，他们将面临什么。你正在描述地形的布局、他们将遇到的对手、他们可以使用的武器和能量道具等等。你不必告诉他们如何完成任何事情，你只需要向他们解释按下哪些按钮才能直接开始，以及当他们意识到他们可能应该首先学习一下时，应该翻到哪个章节或部分。

其他所有内容

听着，到了这个时候，你已经掌握了你的用户。应用程序不再可怕，他们准备开始使用它了。如果用户到了核心内容部分，那么他们更需要的是通用电气冰箱维修手册。我更喜欢写得比字面意义上的冰箱维修手册更人性化一些，但这部分是给出细节、分析工作流程、讨论框架、揭示设计理念、解释概念等等的地方。

如果用户在这里，那么他们使用你的应用程序的程度足以知道要问什么。在这里，你可以详细说明每个按钮、每个菜单项的功能，以及哪个窗口面板做什么。

证明它

我知道你在想什么。你认为快速的三步介绍是做不到的，或者如果做到了，那将是一个无用、陈腐的介绍，实际上并没有传达有用的信息。

但我不敢苟同。知识共享游戏 Dungeon Delvers 仅用六页扑克牌大小的框架创建了一个功能齐全的角色扮演游戏 (RPG) 框架，这些框架旨在折叠成小册子并放在你的钱包里，这样你就可以确保在突然爆发角色扮演的情况下始终拥有 RPG 规则书。

Dungeoneer 臭名昭著的复杂规则集被压缩到一张卡片上，作为提醒玩家回合阶段的提示。

所以不要低估“电梯演讲”的力量。并非所有内容都可以用字面意义上的“3 个简单步骤！”来介绍，但我保证，如果你以此为目标，那么你的文档将创造奇迹。

举个例子，这是一个视频编辑器的快速介绍。不一定是最容易介绍的应用程序类型，对吧？这可能是不可能的，但让我们试一试：

1. 启动 Flowblade 并单击中间面板中的添加按钮。
2. 双击中间面板中的剪辑缩略图，在右侧的视频监视器中打开视频。
3. 使用键盘上的 i 和 o 键，标记你喜欢的素材的入点和出点。使用中间按钮栏最右侧的“追加”按钮将其添加到你的时间轴。

你正在编辑视频！要了解有关编辑的更多信息，请参阅第 blah blah blah 章。

或者，也许这还是有可能的！当然，对于“3 个简单步骤”来说，有很多复合句，但你的读者不会注意到；他们正忙于按照说明操作，并被你的编号列表中的大数字弄得眼花缭乱！

你看，我不是说文档是诚实的。事实上，我说这完全是表演！快速抓住你的读者，让他们开始使用你的应用程序，他们就会忘记他们最初开始时有多害怕。

例外情况

诚然，有些东西确实不适合这种完美的模型。我会为复杂的、可扩展的网络文件系统 GlusterFS 写一个三步介绍吗？不会，但 Gluster 团队写了一个六步介绍，这 A) 是三的倍数，B) 非常棒。

我会为 RAID 式文件系统管理器 LVM 写一个三步介绍吗？不会，但我见过有人用 七个步骤 完成了它（可以说，如果我固执的话，可以重新结构化为六个或三个步骤）。

例子可以继续下去，但重点实际上不是我们是否可以将 Postfix 配置简化为三个简单的步骤（据我所知，我还没有做到），而是我们是否旨在编写简化的文档来提供一个入口点，或者我们只是用应用程序代码中包含的每个数据类型的清单来猛击潜在用户，邀请他们在弄清楚所有这些意味着什么之后，从中编写自己的该死的用户指南。

下次你编写一些文档时，不妨试一试。你可能会让自己感到惊讶，更重要的是，你的用户。