你还记得大富翁、人生之旅和线索，以及所有那些你小时候玩的经典棋盘游戏吗，因为有时候你就是那么无聊？你还记得曾经读过说明书吗？可能没有，因为没人会读那些游戏的说明书。我们都有一个朋友，他大概知道怎么玩游戏，所以他们教我们怎么玩，这就足够了。（说真的，回去重读一下大富翁的说明书；我敢用网络上的钱打赌，你从来没有真正按照规则玩过这个游戏。）
如果你真的尝试去读说明书，你会发现它们是在 1962 年写的，读起来几乎和通用电气冰箱的维修手册一模一样。它们同样详细、同样完整，也同样无趣。
这听起来是不是很熟悉？
再想想。这听起来是不是太熟悉了？嗯，应该是的，因为这正是软件文档今天仍然存在的问题。
桌面游戏说明书
我永远不会忘记第一次买现代桌面游戏。我打开盒子，深吸一口气。是时候读说明书了。
令我惊讶的是，说明书只写在半张纸上，字体很大，留白很多，还有三个很大的数字，配有宜家风格的插图，几乎具有侮辱性的明显
- 给每位玩家发五张牌。（一张五张牌的手牌图片，向读者展示他们在游戏中会遇到的不同类型的牌。）
- 将任务牌放在桌子上，按照指示进行游戏。（任务牌的图片。）
- 每回合出两张牌。按照牌上的指示去做。第一个完成最近打出的任务牌上所写内容的人获胜。
“你正在玩了！”
就是这样。这些是（为了这个例子而修改的）说明。三个步骤和一个大喊，嘿，别看了，但你已经在玩游戏了，而且你已经开始运行了。
公平地说，这三个步骤并没有涵盖很多细微之处。幸运的是，作者在“你正在玩了！”的宣告之后偷偷加入了另外三个段落，提供了关于牌的类型、它们的含义等等的更多细节。
在最初的几局游戏中，我们有很多次不得不停止游戏，挠着头问：“等等，我们不能在那张牌之后出这张牌，是吗？现在会发生什么？”为了找到答案，我们回到规则，查看规则表背面的小参考部分，在游戏中学习游戏的细则。
但你看，它欺骗了我们；我们感觉不像是在读说明书，因为我们正在积极地玩游戏。我们没有在读说明书，实际上；我们是在使用规则作为参考。它实际上是游戏的一部分。
使软件文档成为游戏的一部分
并非所有东西都适合三个步骤、三个后续段落和一个参考部分。但是，当你以它为目标时，你会惊讶于说明书会变得好得多。例如
三个简单的步骤
- 为你的读者提供一个清晰的入口点。阅读用户指南的人想知道如何使用你的应用程序，而不是理解驱动你编写它的理念。
- 列举用户必须做的事情。这是一种良好的床边方式；这不是绝对必要的，但它可以帮助用户准确理解你的应用程序对他们的期望。这是一个清单，让他们知道这些是接近这个应用程序的正确步骤。
- 让你的用户从跳板上起跳，而不是掉进布满尖刺的坑里。在你的列举的“入门”列表之后，确保你的用户准备好更进一步。这是你的推销：看看入门有多容易！只需要三个步骤！现在你不想读接下来的三个段落，找出你可以从这里做什么很酷的事情吗？如果你的用户在完成你的三步介绍后，盯着一个空白屏幕，不知道接下来可能会发生什么，那么你需要重写你的文档，或者你可能需要重写应用程序。
就是这样！
是的，经常向你的用户宣布他们在你的文档中的位置。这可能看起来很屈尊，但你的读者不知道他们成为这个奇怪的新应用程序的专业人士的道路上走到哪里了。所以告诉他们。他们是否刚刚完成了你的应用程序 50% 的功能？或者他们所做的只是配置它，以便它将在他们的系统上启动？告诉他们。让他们知道。要清晰、诚实、兴奋。向他们保证，这一切都非常正常，并让他们了解正在发生的事情，例如他们是否应该每次坐下来使用该应用程序时都执行这些步骤，或者这是否是一次性设置，他们永远不会再做。
沟通。
而这应该是所有的介绍。简单、令人放心、肯定、自我膨胀。你只是在向你的读者推销一个事实，即你保证你的应用程序是平易近人的。他们可以做到这一点。
三个段落
在你向你的读者保证他们可以接受这个应用程序并获胜之后，告诉他们接下来应该去哪里。他们是使用这个应用程序来构建小部件还是分析小部件？它可以做到这两者，所以通往其中一个的路径在第 3 章，而通往另一个的路径在第 4 章。他们是在服务器上设置这个应用程序，还是将在本地使用？相应地转到第 5 章或第 6 章。等等。
后续部分的目的是警告你的读者，一旦他们真正开始工作，他们将会遇到什么。你正在描述地形的布局、他们将遇到的对手、他们可以使用的武器和能量提升等等。你不一定需要告诉他们如何完成任何事情，你只需要向他们解释按哪些按钮才能直接进入，以及当他们意识到他们可能应该首先学习一下时，应该翻到哪个章节或部分。
其他一切
听着，到这个时候，你已经拥有了你的用户。应用程序不再可怕，他们准备开始使用它了。如果用户到了肉和土豆部分，那么通用电气冰箱维修手册或多或少是他们正在寻找的。我更喜欢写得比字面上的冰箱维修手册更人性化一点，但这是可以给出细节、分析工作流程、讨论框架、揭示设计理念、解释概念等的部分。
如果用户在这里，那么他们使用你的应用程序已经足够了解要问什么。在这里你可以详细说明每个按钮、每个菜单项以及哪个窗口面板做什么的功能。
证明它
我知道你在想什么。你认为一个快速的 3 步介绍是不可能做到的，或者如果做到了，那将是一个无用的、陈腐的介绍，实际上并没有传达有用的信息。
但我不敢苟同。知识共享游戏 地下城探险者，仅用六页扑克牌大小的框架就创建了一个功能齐全的角色扮演游戏 (RPG) 框架，这些框架旨在折叠成小册子并放在你的钱包里，这样你就可以始终确保在突然爆发角色扮演的情况下拥有 RPG 规则书。
地下城主臭名昭著的复杂规则集被浓缩到一张卡片上，作为玩家回合阶段的提醒。
所以不要低估“电梯推销”的力量。并非所有内容都可以用字面意义上的“3 个简单步骤！”来介绍，但我保证，如果你以此为目标，那么你的文档将会创造奇迹。
例如，这是一个视频编辑器的快速介绍。不一定是最容易介绍的那种应用程序，对吧？这可能是不可能的，但让我们试一试
- 启动 Flowblade 并单击中间面板中的添加按钮。
- 双击中间面板中的剪辑缩略图以在右侧的视频监视器中打开视频。
- 使用键盘上的 i 和 o 键，标记你喜欢的素材的入点和出点。使用中间按钮栏最右侧的“追加”按钮将其添加到你的时间线。
你正在编辑视频！要了解有关编辑的更多信息，请参阅第 blah blah blah 章。
或者也许这毕竟是可能的！当然，对于“3 个简单步骤”，有很多复合句，但你的读者不会注意到；他们正忙于按照说明操作，并被你的编号列表的大数字搞得眼花缭乱！
你看，我不是说文档是诚实的。事实上，我说这都是表演！快速抓住你的读者，让他们开始使用你的应用程序，他们就会忘记他们开始时有多么害怕。
例外
诚然，有些东西就是不适合这个完美模型。我会为 GlusterFS（一个复杂的、可扩展的网络文件系统）编写三步介绍吗？不会，但 Gluster 团队 编写了六步介绍，这 A) 是三的倍数，B) 非常棒。
我会为 LVM（一个类似 RAID 的文件系统管理器）编写三步介绍吗？不会，但我见过在 七个步骤中完成的（可以说，如果我固执的话，可以重新组织以减少到六个或三个步骤）。
例子可以继续，但重点实际上不是我们是否可以将 Postfix 配置简化为三个简单的步骤（据我所知，我没有能够做到），而是我们是否以提供入口点的简化文档为目标，或者我们只是用应用程序代码中包含的每种数据类型的清单来猛击潜在用户，邀请他们在弄清楚这一切意味着什么之后，从中编写他们自己的该死的用户指南。
下次你编写一些文档时，试一试。你可能会让自己感到惊讶，更重要的是，你的用户。
3 条评论