孙高飞:人工智能测试

无论您从事哪种类型的项目，都不能指望用户自己完全理解它。 那就是文档的来源。文档可以是任何东西，从简单的过程到详尽的用户故事。 当然，Web UI有时可以说出自己的话（最好的话），但是我敢肯定，您已经看到了一些读者质疑基本UI路径或在命令行中执行任何操作的故事。

这就是为什么即使对于最基本的主题而言，创建文档对用户也很重要的原因。

如果您想要更多的证据，让我们谈谈高飞。 高飞（Goof Troop） ， 王国之心 （ Kingdom Hearts ）和众多迪斯尼短裤的可爱明星， 高飞 （Goofy）是“基本用户”的定义。 他尽了最大的努力，即使他有很多问题，他也总是设法失败。 他遇到麻烦的原因之一可能是他使用的文档质量差。 其中很多都是有问题的，直接导致失败，混乱甚至人身伤害。 这就是高飞（Goofy）短篇小说《 如何钓鱼》中发生的事情。

《如何钓鱼》 ，迪士尼，版权，1942年。

好消息是“ 如何钓鱼”是一个很好的例子，说明了为什么好的文档如此重要（以及为什么不好的文档如此重要）。 让我们看一段短片，看看这个看似简单的任务的糟糕文档导致Goofy这么多问题的一些方式。 我还将分享有关如何改进它的建议。

高飞想要学习钓鱼，我们中有些人认为这很容易。 但是有时最基础的用户（例如Goofy）想要从一开始就开始学习，因此，像How to Fish这样的书的相关性。

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

01:20
《 如何钓鱼 》的读者已经渴望钓鱼。 不需要告诉他为什么他想钓鱼。 我要删除它。

01:35
“钓鱼热”是既定名词吗？ “发烧”一词具有负面含义。 如果这是您的原始概念，则可以选择一个更友好的术语，例如“钓鱼热情”。 或者也许保持简单，坚持“钓鱼的欲望”。 如果您想保留此名，也许是“钓鱼的宠儿”。

01:45
在视频中，显示了Goofy测试他的捕鱼设备，但文档中没有列出必要的捕鱼设备。 这很重要，应在先决条件部分中突出显示。

先决条件：

• 钓鱼竿
• 饵

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左右，由于不正确的投射程序而使他飞过空中时。 哪种飞行方法正确？ 钓鱼发烧会导致飞行吗？
• 我很担心本指南中显示的步骤实际上不会带来成功的钓鱼经验。 当高飞在一块岩石上绊倒时，似乎唯一被抓住的鱼被意外放开了。 同样，文档也没有指出鱼是如何被首先捕获的。 最后，高飞最终以马达代替鱼。 如果那是它的目的，也许本指南应该重命名为“如何去钓鱼，而要抓住船上的引擎”。

既然Goofy的困境帮助我们实现了一些常见的文档陷阱，我很好奇：您还有其他提示可帮助为基本用户编写更好的文档吗？ 就像“为每种类型的用户编写内容”一样简单吗？ 随时在评论中分享您的想法。

翻译自: https://opensource.com/article/18/4/documentation-pitfalls-goofy

孙高飞:人工智能测试