我不会烤牛角面包:关于项目文档的寓言

还没有读者喜欢这个。
flour + butter + stuff

Opensource.com

嗨!我是 Mel。当我不做自由软件和开源的事情时,我是一个学习心理学爱好者。我的自由及开源软件黑客朋友经常问我的一个问题是:Mel!为什么没有人帮助我的项目?

Based on a CC-BY-3.0 photo by assbach

基于 CC-BY-3.0 照片,作者:assbach

在我回答之前,他们很快会说

  1. 但是我有文档!
  2. 而且我不会在 IRC 上发脾气!
  3. 真的!

所以我查看了文档,观察他们在 IRC 上与人们互动,很快,我就能回答:“好吧,我知道你的问题是什么了。”

现在,我不打算解释软件方面的问题,我有点饿了,所以我要谈谈牛角面包。

Croissant by Alanna Risse

牛角面包 CC-BY-2.0,作者:Alanna Risse

我正在学习烘焙。我是一个糟糕的烘焙师。我碰一下烤箱,就会有东西爆炸。所以我在烘焙界绝对是个新手。假设我想学习如何烤面包,所以我在线查找一些面包食谱。我可能会遇到一个看起来像这样的食谱

牛角面包

  • 面粉
  • 黄油
  • 东西

混合然后烘烤!

如果您有任何问题,请问我!

我立刻就“bwuuuuh?”然后忽略一切——我不知道从哪里开始。我甚至不确定你在说什么,以及我想要的东西是否相同。我的意思是,牛角面包到底是什么鬼东西?

如果您告诉我这是一种面包,可能会有所帮助。

croissant-madrid CC-BY-3.0 by Tamorlan

croissant-madrid CC-BY-3.0,作者:Tamorlan

牛角面包:美味的片状黄油面包

  • 面粉
  • 黄油
  • 东西

混合然后烘烤!

如果您有任何问题,请问我!

对了!面包!我正在尝试学习烘焙的东西!我现在可能真的想做这东西了。但我仍然不确定具体该怎么做。

那个东西清单是什么?我该如何烘烤它?没人告诉我,所以我出去买了面粉、黄油,还有……一些东西 - 柠檬糖和棉花糖是东西,对吧?所以我把它们放在碗里混合,现在我……

哦,糟糕。你是说我需要事先准备好烤箱?还要预热它?那到底是什么意思?我做错了什么可怕的事情吗?

我应该放弃然后走开吗?

based on cornetti1 CC-BY-SA-3.0 by exeair

基于 cornetti1 CC-BY-SA-3.0,作者:exeair

相比之下,看看这个 WikiHow 牛角面包制作指南。这里有一个清晰的配料表:4 杯面粉、1 汤匙活性干酵母(2 包),等等。这里有步骤。它们是图文并茂的。它们告诉我面团应该是什么样子(“光滑有弹性的稠度”)以及每个步骤需要多长时间(“直到它的大小翻倍……应该需要 1.5 到 2 小时。”) 天哪,步骤 20 甚至告诉我打开烤箱,以便它预热并在步骤 22 中准备就绪,并且最后列出了与牛角面包搭配良好的东西(黄油、果酱、火腿、奶酪)。并且有一张最终结果的图片,让我垂涎欲滴。

我们知道这些清晰的分步说明在食谱中很重要,因为我们在烘焙领域大多是新手。我们不能仅仅靠即兴发挥,因为我们不知道这些成分将如何相互作用;我们不熟悉糕点制作,因此即使是常用的工具和技术也会很陌生。我们以前从未制作过(甚至可能从未吃过)牛角面包,因此如果没有帮助,我们就无法想象这个过程或最终结果。

The Mel approves

我们没有上下文

然而,我们认为像这样的说明应该能被所有人类理解

下载这些 tarball,编译它们,一切都应该可以工作。

对于我们这些经验丰富的软件黑客来说,这是可以理解的——大多数时候,当我们编写这样的文档时,我们仅仅是提供一个我们在测试中已经做了几十次的例子的例子。我们是专家。我们以前都做过,我们知道会发生什么,粗略的笔记足以让我们重现过去的结果。

但是我们的受众不是。上下文很重要。经验很重要。而且你永远不能假设你的受众——那些追随你的人——会拥有这两者,尤其是不会以与你完全相同的方式拥有这两者。

因此,如果您想知道为什么人们不遵循您的指示来帮助您的项目,请去当地图书馆借阅一本食谱。烘烤一些您从未烘烤过的东西。(如果您是一位优秀的烘焙师,请尝试制作纯素甜点或无麸质面包 - 做一些不熟悉的事情。)注意作为新手的感觉。注意哪些说明让您感到紧张,哪些说明让您感到自信。然后,在享用您的劳动成果时,再次打开您的文档,并以您的“初学者心态”查看它。

如果您想了解更多关于任何给定领域中新手和专家思维之间差异的信息,请查看德雷福斯技能习得模型,这正是关于牛角面包的整个部分秘密要表达的内容。

今天我们的时间就到这里。谢谢大家。

本文最初是在 FUDCon Tempe 上发表的 5 分钟闪电演讲。

标签
User profile image.
Mel Chua 是一位极具感染力的热情黑客、作家和教育家,拥有超过十年的教学和课程开发经验,并在 Red Hat、One Laptop Per Child、Sugar Labs、Fedora 和其他自由、开源和开放源代码软件 (FLOSS) 社区担任领导职务方面有着良好的记录。

10 条评论

作为一名项目经理,我发现我花了很多时间向参与我的项目的工程师解释,为什么他们“只是理解”的文档对于我们随产品发布的文档来说不够好。这是一个很好的例子,我将与他们分享。希望这次工程师们“只是理解”了。:)

我一直在内部网中实现一个功能,这个功能是由一位同事开发的,并编写了文档(他承认文档是拼凑起来的,并非用于消费)。

理解所有内容并不容易,部分原因是他在最初构建它时知道很多假设,以及它应该如何工作。他也没有写下一些变量的具体名称以及它们应该如何使用。

我已经磕磕绊绊地完成了它,现在我已经掌握了*我*的不足之处,我正在努力填补文档中的空白,以便下次(以及对于下一个人)必要的工具将被阐明。

每当我为任何东西(文章、教程等)编写文档时,我都会记住一个人;我的妻子。我非常了解她,我知道她对计算机不够精通,所以我必须非常仔细(并且可视化地)描述事物。有时当我查看我正在做的事情时,我可以听到她在我脑海中的声音,我会听从它。我用她作为我写作对象的形象,以避免将任何事情视为理所当然。

它并不总是有效,但它有帮助!

我喜欢你的例子的一点是,你心中有一个特定的人——你的妻子——而不是一个广泛的“开发者”类别,这是一个模糊的统称,难以测试。你如何检查为你妻子编写的文档是否有效?你把它展示给你的妻子。你如何检查为“开发者”编写的文档是否有效?嗯……

最好为特定的开发人员编写文档 - 或者让该开发人员为您编写文档,正如您所指出的那样。找一个实习生,说你要教他们做一些很酷的事情,他们会把它写下来,并在他们的名下获得一篇技术写作,他们可以获得全部功劳,你会帮助编辑。实际上,他们为文档中的教学付费,这是一种吸引新人加入项目的绝佳策略;“初学者心态”可能是一种强大的工具,如果它伴随着描述它的表达能力。

最后,在描述您如何填补您发现的文档空白时,您完美地说明了“让事物比您发现时更好”的规则,这些规则使项目 - 和客厅 - 保持理智状态。

但是,是的,为特定的人写作(并让这些特定的人测试写作 - 即使是简短的测试)很重要。这就是为什么专业设计师使用角色而不是“市场细分”。我为我 13 岁的表弟、我的男朋友、我的老板、我团队的实习生、我钦佩但又太害羞而不敢问问题的开发人员写过文档,除非提供一些有价值的回报(“如果你教我如何做这个,我会写下说明,这样你就再也不用教任何人了!”)。对我来说,关键实际上是让那些人在我写完文档后检查文档。而且,如果您还没有被一个 13 岁的女孩撕毁您的文档……这真是一次令人谦卑的经历。

大多数程序员意识到的,但学校没有教的是,文档有两种类型:一种是给用户的,另一种是给代码维护者的。由于它们服务于不同的目的,因此必须分开完成。给用户的文档应该由您的技术作家编写,并接受您的程序员的意见,但给维护者的文档应该完全由您的程序员编写。而且,编码标准经常要求进行描述,这导致代码以糟糕的英语重复。应该作为文档的是代码的目的;为什么要这样做而不是其他方式。这将告诉维护人员,如果他们对代码进行重大更改可能会发生什么。两种类型的文档服务于两种不同的目的。

好观点 - 我应该区分一下。最初的演讲是面向开发人员的(我自己也是一名工程师),所以我心中想到的是开发人员文档;在任何技术项目中,我最讨厌的事情之一是,很少有工程师让其他工程师测试他们的文档,然后想知道为什么没有人可以与他们的组件交互或扩展他们的组件。

记录代码的目的以及做出决策背后的理由也是一个极好的观点。我见过很多年轻的开发人员加入一个项目,然后说“他们为什么要使用 $technology_foo?他们一定是白痴;为什么不使用 $technology_bar - 我可以在 2 小时内用 $technology_bar 重写它!”(或类似的说法),然后与资深的开发人员交谈,了解产品是在 $technology_bar 不稳定时编写的,或者为其制作产品的客户坚持使用 $technology_foo,然后证明 $technology_bar 在十几个用户之后崩溃,并且无法移植到不同的浏览器,并且不可扩展,等等。

版本控制和保留会议记录(在其中记录这些类型的辩论和决策)是帮助跟踪此问题的好方法,因为不,当您签入代码时,您的逻辑和决策过程不会神奇地嵌入到您的代码中。

那么,是什么促使某人在他们的文档中提供清晰的上下文?我认为您必须对您的客户有一定的爱或欣赏——并希望他们欣赏您帮助了他们。如果这种“爱”不是天生的,那么您可能需要一个反馈循环。

还记得那个有趣的儿童游戏吗?一个孩子(蒙着眼睛)给出一些简单的事情(例如打结、制作花生酱和果酱三明治或摆桌子)的分步说明,而其他孩子必须完全按照步骤进行,不要填补空白——然后看到随之而来的混乱。然后,蒙着眼睛的“指导员”看到了荒谬的结果。我希望 tarball 能以这种方式工作。

就我个人而言,我的主要动力是希望有一天我不会维护我编写的任何代码。我很容易感到无聊 - 一旦我充分完成一个项目以解决我自己的问题,我会立即检查它是否解决了其他人的问题……如果解决了,我会尝试让他们更好地解决他们的问题……如果有效,最终其他人最终会比我做更多(和更好 - 我实际上根本不是一个好的程序员)的开发。

当他们超越我,而我实际上成为他们努力的瓶颈和障碍时,我会问他们是否愿意接管维护,以便我可以不妨碍他们的生产力。到目前为止,每个人都说是的。我可以继续使用我最初开发的软件。双赢。但这取决于 - 至关重要的是 - 拥有良好的开发人员文档。所以我通常从我(手动)引导第一个新开发人员完成我的项目破解的聊天记录中编写这些文档,因为(根据定义)它们包含让新人入门所需的所有问题。

然后我可以自由地继续进行我的下一个很棒的项目。

这很好地说明了忽略简单步骤是多么容易。

当参与 QA 时,我对此有了很好的感觉,因为缺少任何步骤都会导致“已解决:无法重现”的更新,并受到开发人员的蔑视。经过仔细审查,您意识到在步骤 3 和步骤 4 之间,应该有一个关于使用 Enter 键而不是单击“登录”按钮(或某些其他可变操作)的注释。

QA 的关键是确保计算机可以按照您的步骤重现问题(计算机比您的配偶、孩子、表弟、非技术亲戚等更字面意思)。我总是记录错误,假设计算机将尝试重现该问题。这意味着在对象/细节参考、动词、引号、大小写等方面保持一致。就像在食谱中一样,如果您反复从“茶匙”切换到“茶匙”,有人可能会感到困惑或开始怀疑自己。

在最终用户文档中,占位符通常会给用户带来安慰。也就是说,仅仅识别出某个部分缺失,或者您的文档中需要更多细节,就可以产生巨大的差异。这是某人迷路并放弃,与同一个人意识到他们在一个被声明为令人困惑的区域迷路之间的区别。这种简单的承认可能会导致用户进一步调查(甚至通过电子邮件/IRC/任何方式与您联系),而不是仅仅寻找不同的项目。

正如 Mel 和一些评论所暗示的那样,问题在于假设其他人都具有与您相同的经验/观点/假设。我也对此感到内疚,现在是时候停止抱怨编写文档了。即使这很痛苦,也要开始更新它,以便任何人都能理解您想要表达的内容。从长远来看,这将节省大家很多时间。

对于我们这些想要参与开源的人来说 - 找到令人困惑的文档,并联系项目参与者来修复它!不要放弃,也不要只是抱怨,这是开始参与的完美途径,您可以在此过程中学到很多关于项目的信息。

这个概念的名称是 推论距离 - 您的陈述所依据的假设知识,某人在理解您的句子含义之前需要了解的事物。

是的,每个极客都需要理解这个概念 :-) 极客们倾向于 期望较短的推论距离 并遭受 透明度错觉 - 您的文字向他人传达的信息比实际传达的更多的误导性印象。

沟通仍然是一个难题,即使它是我们的大脑专门进化出来处理的问题。

让我补充我的 2.0e-2 美分。
从非常非常一般的角度来说(您的里程可能会有所不同),我发现在一些 OS 项目中我更缺少的是对软件结构的非常高层次的视图。通常您会在 /doc 目录中找到一组自动生成的 *.html 文件,其中包含类的继承图和函数的原型。这是过于详细的文档。如果您是一位经验丰富的开发人员,那么拥有一件可以提醒您 Audio_Bugaboo 继承自 Multimedia_Bugaboo,而 Multimedia_Bugaboo 又继承自 Abstract_Bugaboo 的东西可能会很有用,但对于一个不知道 Bugaboo 是什么以及它应该做什么的新手来说,一个粗略的框图,显示 Bugaboo 在哪里进入画面,可能会更有用。

我希望看到一些文档(以及我通常放置文档的地方)的另一个位置是在 *.h 文件中(嗯,实际上是在 *.ads 文件中。我使用 Ada...)。从我的角度来看,开发人员是您的 .c 文件实现的小模块的用户,而放置模块使用说明的最佳位置是 .h 文件。但是,通常您在 multibugaboo.h 中找到的是类似于以下内容的一行注释


/* multibugaboo.h: Multibugaboo 实现 */

呃……真的?!这是一个惊喜……
Multibugaboo 到底是什么鬼东西?!它的职责是什么?!!?这个模块提供了什么类型的函数/过程/数据结构?!顺便说一句,没有必要详细描述 multibugaboo 的内部细节(如果您真的需要,请将它们放在 .c 文件中),只需一个非常高层次的描述就足够了,这样如果我正在搜索格式化数据包并在网络上发送数据包的代码,我就知道我是否在正确的文件中。

[[ 抱歉,发牢骚了……想象一下旁边有很多微笑 :-) :-) :-) 我在写作时在微笑,但电子媒介不传递这种侧面信息。]]

因此,最重要的是,高层次的文档是新手经常需要的。矛盾的是,记录最细微的细节可能不是那么重要,它们可以从写得很好的代码中推断出来。此外,如果实现细节发生更改,但注释没有更改,则可能会引起问题。

让我最后告诉您我对这个问题的个人方法。为了实践我所宣扬的,我发现维护一个 wiki(仅由我自己编辑)用作想法的记事本很有用。wiki 为您提供了一种简单的方式来保持您的笔记井井有条,并且速度足够快,不会影响您的思路。最后,经过适当改进的 wiki 应该是高层次概述的良好基础。此外,扫描的手绘图片可以很好地替代稍后使用一些绘图软件制作的图表和内容。当然,您的里程可能会有所不同……

Creative Commons License本作品根据 Creative Commons Attribution-Share Alike 3.0 Unported License 获得许可。
© . All rights reserved.