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

无论您从事什么类型的项目，您都不能指望用户完全靠自己理解它。这就是文档的用武之地。文档可以是简单的步骤，也可以是详尽的用户故事。当然，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 左右，当他因不正确的投掷程序而飞过空中时。哪种飞行方法是正确的？钓鱼热会导致飞行吗？
• 我非常担心本指南中显示的步骤实际上不会导致成功的钓鱼体验。唯一看起来被钓到的鱼是高飞绊倒石头时不小心放走的。此外，文档没有说明鱼最初是如何被钓到的。最后，高飞最终得到的是发动机而不是任何鱼。如果这就是它的目的，也许本指南应该更名为“如何去钓鱼，但钓到船用发动机”。

现在高飞的困境帮助我们认识到了一些常见的文档缺陷，我很好奇：您是否有其他技巧可以帮助为基本用户编写更好的文档？它是否可以像“为每种类型的用户编写”一样简单？欢迎在评论中分享您的想法。