高飞学钓鱼：为什么好的文档很重要

无论你正在进行什么类型的项目，都不能指望用户完全靠自己理解。 这就是文档的用武之地。 文档可以是简单的步骤，也可以是详尽的用户故事。 当然，Web UI 有时可以不言自明（最好的 UI 确实如此），但我相信你一定听说过读者质疑基本的 UI 路径，或对在命令行上执行任何操作感到不安的故事。

这就是为什么创建文档——即使是最基本的主题——对用户来说也至关重要。

如果你想要更多证据，让我们来谈谈高飞。 可爱的高飞是 高飞家族、王国之心 和众多迪士尼短片的明星，他是“基本用户”的典型代表。 他尽了最大的努力，即使他有很多问题，但他总是能莫名其妙地化险为夷。 他遇到麻烦的一个原因可能是他使用的文档质量很差。 很多文档都有问题，直接导致失败、困惑，甚至人身伤害。 这就是在高飞的经典短片 如何钓鱼 中发生的事情。

如何钓鱼，版权所有，迪士尼，1942年。

好消息是《如何钓鱼》是为什么好的文档如此重要（以及为什么坏的文档会成为问题）的一个绝佳例子。 让我们来看一下这部短片，看看关于这项看似简单的任务的糟糕文档是如何给高飞带来这么多问题的。 我还将分享我关于如何改进它的建议。

高飞想学习钓鱼，这对我们中的一些人来说是一项非常容易的任务。 但有时最基本的用户（如高飞）想从头开始，因此像《如何钓鱼》这样的书就有了意义。

00:40
我们得到了很多关于地球潮汐和水体如何运作的背景知识。 这有必要吗？ 我会删除关于海王星和宇宙振动的部分。 也许本节应该参考关于最佳钓鱼时间以获得最佳效果的资料。

01:20
《如何钓鱼》的读者已经有钓鱼的愿望。 他不需要被告知为什么他渴望钓鱼。 我会删除这部分。

01:35
“钓鱼热”是一个既定的术语吗？ “热”这个词带有负面含义。 如果这是你的原创概念，也许可以选择一个更友好的术语，例如“钓鱼热情”。 或者，也许保持简单，坚持使用“钓鱼的愿望”。 如果你想保持头韵，也许可以用“对钓鱼的喜爱”。

01:45
在视频中，高飞展示了测试他的钓鱼设备，但在文档中从未列出必要的钓鱼设备。 这很重要，应该在先决条件部分中突出显示。

先决条件

• 鱼竿
• 鱼饵

01:50
这个关于抛竿动作的快速介绍很有帮助，但是否应该有更多信息？ 这会在未来某个地方概述吗？

此外，我建议加入故障排除警告

警告： 不要在室内钓鱼。 可能会引来错误的鱼，并增加头部受伤的风险。

02:00
关于：“垂钓者可以很容易地想象在清澈的水池中有一条斗鱼。” 这种说法非常含糊。 我理解 斗鱼原产于东南亚。 本指南的读者是否应该在东南亚钓鱼？ 请定义“清澈的水池”。

02:08
本节标题为“在哪里钓鱼”，但只提到了一个地点（“高耸崎岖的山脉”，这不太可能是鱼的栖息地，鱼生活在水中），并且仅指环境的“感觉”。 可以用以下内容更好地概括这一点

在哪里钓鱼

• 山间河流或溪流

02:40
视频的这一部分暗示了露营/钓鱼之旅所需的设备。 是否应该列出登山钓鱼之旅的装备清单？ 请参阅我上面关于在先决条件中列出必要设备的评论。

02:50
这里描述了鳟鱼的特征。 这对于了解如何捕捉鳟鱼是必要的吗？ 鳟鱼是文档涵盖的唯一鱼类吗？ 如果是这样，是否应该将标题更改为：“如何钓鳟鱼”？ 是否应该扩展文档以包括其他鱼类？

03:20
这里是否应该有一个警告？ 例如

务必悄悄地潜行，并注意你的去向，否则，你可能会从山上掉下来，衣服挂在树上。

04:00
我们将受益于更多关于飞蝇钓的背景知识以及它导致鱼嘲笑渔民的原因。

04:25
在关于鱼饵的部分，高飞移动一根细绳，使鱼饵跳出复杂的舞蹈。 你能提供更多关于这是如何运作的信息吗？ 音乐的风格重要吗？ 如果是这样，也许需要一个表格，其中包含关于不同类型音乐及其对鱼的影响的信息。

04:40
最好添加另一个警告

警告：当用跳舞的鱼饵引诱鱼时，确保不要倒退到溪流中的岩石上。 这可能导致人身伤害和失去之前捕获的鱼。

04:55
如果将此抛竿的解释放在文档的更靠前位置，将会更好。 也许在 03:20 左右，当首次解释钓鱼时。

解释不同类型的钓鱼（例如，飞蝇钓、鱼饵钓、蚯蚓钓等）的不同抛竿方法是否有好处？ 这在比较表中会很好用。

05:02
虽然文档似乎准确地解释了实现“完美抛竿”（如 05:36 所述）的正确手臂动作，但高飞的抛竿部分成功，他的鱼线“嗖嗖”作响，但他没有钓到鱼。 是否有其他细节可以帮助他避免将鱼线抛到树上？

05:50
文档在这里区分了湖钓和其他类型的钓鱼。 是否最好将上面的部分更改为“河流钓鱼”？ 此外，对于湖钓，我们需要单独的先决条件部分吗？

先决条件

• 船

06:04
高飞钩住了他的船用发动机。 关于船用发动机的警告会有帮助吗？

警告： 在移动的船上时，不要进行卷线轮抛投。 这可能会导致鱼线缠绕在旋转的发动机叶片中，并让你错误地认为自己钓到了一条大鱼。 相反，这可能会导致你的船用发动机和船只的损失，因为它会被发动机叶片切成多块。 如果你不小心钩住了你的发动机，只需松开鱼竿，否则，发动机会将你带入水中，你可能会撞到树上。

06:15
文档的这一部分包含一些关于鱼（或船用发动机？）被钩住时该怎么做的实用技巧，但它们是用不同的声音快速说出的。 这些可以以更合适的方式列出吗？

其他一些想法

• 在 01:35，高飞飞到空中，据推测这是“钓鱼热”（正如你所称）的症状。 我认为这项技能对读者在说明书的其他部分会有好处，尤其是在 05:30 左右，当他因不正确的抛竿程序而飞到空中时。 哪种飞行方法是正确的？ 钓鱼热会导致飞行吗？
• 我很担心本指南中显示的步骤实际上不会带来成功的钓鱼体验。 唯一看起来被钓到的鱼是在高飞被石头绊倒时意外放走的。 此外，文档没有说明这些鱼最初是如何被钓到的。 最后，高飞最终得到的是发动机而不是任何鱼。 如果这就是它的目的，也许应该将本指南重命名为“如何去钓鱼，但最终钓到的是船用发动机”。

既然高飞的困境帮助我们认识到了一些常见的文档陷阱，我很好奇：你还有其他关于如何为基本用户编写更好的文档的技巧吗？ 能不能简单到“为每种类型的用户编写文档？” 欢迎在评论中分享你的想法。