Question

将代码写清楚的能力或许是开源环境中最重要的一项技巧。从长期来看，这不仅仅取决于编程天赋。即使是优秀的程序员，如果没有好的沟通技巧，在同一时间也只能完成一件事，即使如此也很难让其他人注意。但一个糟糕的程序员如果善于交流，则可以协调并说服许多人做很多事情，对于项目的方向和动力起着重要的作用。

无论从哪个方向看，编写好代码的能力和与其他人交流的能力看起来毫不相关。编码能力和描述技术问题的能力则有一些关系，但是描述技术问题只是项目交流中很小的一部分。更重要的是移情到其读者的能力，可以像其他人那样去看待自己的文章和回复，可以让他人以同样的客观性看待自己的文章。同样重要的是发现某种媒介或交流方法不再有效，这或许是因为它并没有随用户数量的增多而扩展，然后花时间去解决它。

在理论上很明显—但因为开源软件开发环境的受众和交流机制引起的混乱，在实践中的非常困难。一个给定的想法必须在邮件列表中作为bug跟踪系统的注释或代码的说明发布出来？当在一个公共论坛回答一个问题时，应该如何假定读者的知识水平，只是为咨询问题的“读者”解答，而是为所有会看到回复的读者？如何让开发者与其他用户保持建设性的联系，而避免陷入特性请求、虚假的bug报告和一般的聊天。如何知道一个媒介达到了容量的限度，你该如何做呢？

针对这些问题的解决方案都只能是部分的，因为任何特定方案都会随项目结构的成长或变化而废弃。他们也经常是专门的方案，因为他们需要随机应变。所有的参与者需要意识到交流在何时，如何陷入困境，并立刻参与到解决方案中去。帮助人们完成这件事是管理开源项目的重要任务。本小节后面的部分会讨论如何引导你自己的交流，以及如何在项目中为所有人维护交流机制的优先级。^[22]

人如其文

考虑如下情况：因特网上别人对你的了解都来自你所写的东西。你或许是一个富有才华、敏锐和领袖气质的人—但是如果的你的邮件散漫且没有组织，人们会以为你也是这样。或者也许你是一个散漫和无组织的人，但没人会知道这一点，只要你的文字能够清晰且言之有物。

在写作上的投入回报巨大。长期自由软件黑客Jim Blandy说过这样一个故事：

回到1993，我为自由软件基金会工作，正在为GNU Emacs的19版本进行beta测试。我们每周都会发布一个这样的beta版本，人们会进行测试并回馈我们bug报告。有一个我们都不认识的人，但是完成的工作很好：他的报告总是十分清晰，并能让我们直接找到问题，而且当他自己提供修正时，也几乎都是正确的。他是顶尖人物。

现在，在FSF可以使用其他人编写的代码之前，我们会让他们准备一些文书工作，将该代码的版权利润赋予给FSF。完全获得陌生人的代码是处理法律灾难的好办法。

所以我给这个家伙发了一份表单，说，“这里是我们需要的一些文书工作，你签署这一份，让你的雇主签另一份，然后我们就可以开始提交你的修正。非常感谢。”

他回复了一封信息说，“我没有雇主。”

所以我说，“很好，那就让你的大学签署它并发回来。”

不久，他又回复了，并说，“很好，实际上，我已经30岁了，与父母一起住。”

因为那个小孩并没有像30岁的人那样写东西，所以没有人知道他的情况。下面也是让你的写作能够带来良好印象的一些方法。

结构和格式

不要像编写手机短信那样编写所有的东西。要使用完整的句子，每个句子首字母要大写，也要根据需要分段。在编写电子邮件和其他内容时这一点最重要。在IRC或类似的短命论坛上，忽略大小写或压缩形式的常见短语也无所谓。只是不要把这个习惯带到更正式，会持久化保存的论坛中。邮件、文档、bug报告和其他会永久保存的东西，必须使用标准语法和拼写，并有一致的叙事结构。并不是因为任何事情都有遵循任意规则的内在特性，而是因为规则并不是任意的：他们演化成现在的形式是因为可以让文本更可读，因此你应该遵循这些规则。可读性是令人向往的，并不是因为这样人们就能够理解你所写的，而且是因为这样可以让你看起来像是人们可以花时间进行清晰交流的人：也就是值得人们关注的人。

对于个别的电子邮件，有经验的开源开发者会使用特定的约定：

只发送文本邮件，而不应该是HTML、富文本或其他格式，因为有许多只支持文本的邮件阅读器。将每行列长格式化为72。列长不要超过80，80已经成为事实上的标准终端宽度（也就是会有人使用更宽的终端，但没有更窄的）。通过将列数设置为小于80，可以为其他人回复中的引用字符留出空间，从而不必让文本强制换行。

使用真正的换行。一些邮件程序可以使用一种假的换行，可以让你编写的邮件在没有实际换行时显示出来有换行。当邮件发送以后，邮件不会有你所以为的换行，他们会非常难看的出现在某些人的屏幕上。如果你的邮件程序使用假换行，应该找一个恰当的设置，可以在编写邮件时显示真换行。

当包含屏幕输出，代码片段或其他格式化文本时，需要清晰的处理缩进，这样可以轻易的区分你的叙述和引用的内容。 （当我开始撰写此书时，我没有想过编写这些建议，但是当在许多开源邮件列表中看到了很多人混合文本和其他资源，以至于无法区分开时，我改变了注意。这样的效果很让人灰心。这让他们的文章很难被理解，很明显也让这些人看起来有点混乱。）

当引用其他人的邮件时，可以直接在合适的位置插入你的回应，如果需要可以在不同的位置，然后删节那些在你的邮件不使用的部分。如果你需要为全文进行评述，可以写在顶部（将你的回应置于引用的邮件文本之前）；否则，请首先引述原邮件的相关文本，然后紧跟你的回应。

小心构建新邮件的主题行。这是邮件中最重要的一行，因为它可以让项目中的其他人决定是否进一步阅读。现代邮件阅读软件可以将相关信息组织成一组线索，并不仅仅是根据共同的主题，而且可以根据其他头（有时并不显示）。它遵循了如下原则，如果线索转移到另一个主题，你可以—也必须—根据回复修改主题行。由于其他邮件头，线索的完整性得以保全，但是新的主题可以帮助人们获知主题已经转移。同样的，如果你确实希望开始一个新的主题，那么可以发布一个新的邮件，而不是对现有邮件修改主题并回复。否则，你的邮件会仍然分组到你所回复的线程中，因此会让人们不知道讨论的内容已经改变。再次，惩罚不仅仅是所浪费的时间，也会使你使用交流工具的信用受损。

内容

组织良好的邮件会吸引读者，但是内容可以留住他们。当然，没有可以确保好内容的固定规则，但是有一些可以让其更像的原理。

让事情对你的读者更简单。任何一个开源项目都有大量的信息，不能期望读者熟悉所有的东西—事实上，不可能期望他们知道如何熟悉。所以要尽可能让你的文章以尽量便利的形式提供给读者。如果你能够额外花费几分钟在邮件列表归档中找出特定线索的URL时，从而减少读者寻找的麻烦，这样做非常值得。如果你可以花费5到10分钟为复杂的线索总结一个结论，从而为人们理解你的文章提供一个上下文环境，那么一定要去做。可以这样考虑这件事，项目越成功，在任何论坛中的读者-作者比率越高。如果你的文章被n个用户看到，那么随着n的增大，扩展额外的努力节约其他人的时间就越值得。随着人们看到你将自己置于这个标准之下，他们也会在自己的交流中与此匹配。理想情况下，会带来项目整体效率的提升：当人们在n个人和一个人这样努力做出选择时，大家会选择前者。

不要使用夸张法。在线发布中的夸大是经典的军备竞赛。例如，一些报告bug的人会担心开发者不会投入足够的注意力，所以他们将其描述为严重的、会中断他（以及他的所有朋友/同事/亲戚）使用该软件的问题，而实际上只是一般的不适。但是夸大并不限于用户—程序员也会在技术讨论时也这样做，特别是当问题是关于他们不认可的某种口味而不是正确性时。

“这样做事会让代码完全不可读。 与J. Random的建议相比，这是维护的梦魇。”

当措辞不是如此尖锐，同样的感情也会变得更强：

“这样也可以工作，但是出于可读性和可维护性的考虑，并不是理想的方式，我认为。J. Random's的建议避免了这类问题，因为它...”

你不可能完全消灭夸大，一般来说也没有必要。与其他形式的交流问题相比，夸大并不是对所有人都有害—他只会伤害夸大者。接收者也会做出相应的抵消，每次都会让发送者损失自己的信用。因此，为了你自己在项目的影响力，请使用温和的方式。只有这样，人们在会在你真的需要表达强烈观点时重视你。

编辑两次。对于任何超过中等长度段落的信息，请在你第一次认为完成之后再从头到尾检查一遍。这是所有参加过写作课程的人会得到的忠告，但是在在线讨论中格外重要。因为在线写作的过程很容易变得非常不连贯（在编写信息的过程中，你需要回头检查其他邮件，访问特定的网页，或者运行某个命令捕获调试信息等），这样很容易让你失去叙事的感觉。不连贯编写的信息，而且在发送以前也不检查通常会被认为会让他们的作者懊恼（或者这样某人会希望）。花时间检查你发送的内容。你的内容组织的越好，就会有越多的人去阅读。

基调

在写过几千条信息后，你一定会发现自己会趋向于简洁。这看起来是大多数技术论坛的标准，在本质上没有任何错误。在社会交流中不可接受的简洁程度则是自由软件黑客的默认程度。下面是我在一个邮件列表中发表的关于自由内容管理软件的文章，完全引用：

您能更详细的说一下所遇到的问题吗？
可能是：

您使用什么版本的Slash？你能说出原始信息吗。
你是如何编译的apache/mod_perl源？

你尝试过发布在slashcode.com的Apache 2.0补丁吗？

  Shane

这就是简洁！没有问候，没有他的名字以外的签名，整个信息本身只有一系列尽可能紧凑的疑问句。其中的一个祈使语句是隐含的对原始信息的批评。虽然如此，我还是很高兴看到Shane的邮件，并没有因为其简洁而把他当作一个大忙人。事实仅仅是他们在询问问题，而不是忽略我的问题，意味着他愿意在这个问题上花更多的时间。

读者能够对这种方式作出正面的反应吗？这不是必须的；这取决于人和上下文。例如，如果某人刚刚承认她犯了一个错误（例如写了一个bug），而你根据以前的经验知道这个人容易不安全，那么你仍会编写一个紧凑的回复，你应当确信其中包含一些考虑其感受的内容。你的回复可能很简短，只有工程师对于形式的分析，和你想的一样简洁。但是在最后，应该指明你的简洁不应该理解为冷漠。例如，如果你要建议如何正确的修正某个bug，应该签署“好运，<这里是你的名字>”指明你希望他们做好工作而不会发疯。一个笑脸或其他符号表情通常也足够安抚你的对话者。

也许像关心参与者所说事情的表面一样关心其情绪有一些古怪，但是认真的说，情绪影响生产力。由于其他原因情绪也非常重要，但如果仅出于功利原因，我们也能发现不快乐的人会写出糟糕的软件。因为大多数电子媒介的本性所限，通常没有关于人们情绪的明显线索。你应该根据这些猜测：a)大多数人在那种形势下的感觉，b)你在以前的交流中对参与者的了解。一些人采用更简单的态度，仅根据表面处理事情，如果没有参与者直接说出自己的感受，则别人没有义务像他已经说出那样去对待她。我不会选用这个方法，有如下一些原因。首先，人们在真实生活中并不是这样处事的，为什么要在线上这样？其次，因为所有的互动发生在公共论坛，人们会比私密情况下更加控制自己的感情表达。更精确的说，他们通常希望对某人直接表达感情，例如感激和愤怒，而不是直接的内部情绪，例如不安和骄傲。当知道其他人会关注到他的心理状态时，大多数人会工作的更好。通过在细微线索上投入注意力，你可以在大多数时候猜到问题，并且能够鼓舞人们比原来更深入地参与。

我不是说，你的角色是团队治疗师，一直通过触及别人的情绪来帮助每个人。但是通过对于个人行为长期模式的观察，即使你们从来也没有面对面，也会获得像单个人之间的感受。而且通过对于自己文章基调的敏感性，你会为自己对于其他人情绪的影响力感到吃惊，最终会使项目受益。

识别无礼

开源文化的一个定性特征是对于何为无礼的特色定义。下面叙述的习惯不只是出现在开源软件开发，也不只是在一般软件—在数学、严密科学或工程纪律中也并不陌生—自由软件，由于其跨领域性，并有不断涌入的新来者，许多不熟悉这种环境的人将要面对这些习惯。

我们先从不无礼开始。

技术批评，即使很直接且没有铺垫，也不是无礼的。实际上，这可以看作是一种谄媚：批评者在说话，说明目标值得重视，值得花时间研究。可以说，平静只是简单的忽视某人的文章，花费更多时间批评它则是更多的赞美（当然，除非批评升级到了非理性的攻击或其他形式的明显无礼）。

迟钝、朴实的问题，例如前面Shane的对我的邮件，也不是无礼。在其他环境下这种提问会看起来有些冷酷，玩弄文字或甚至是嘲弄，通常是有意的严重行为，而且除了尽快释放出信息，没有隐藏的日程表。著名的技术支持问题“你的电脑插电了吗？”是经典的案例。支持者确实需要知道你的电脑是否插电，经过一段时间的这类工作，他已经厌倦了在问题前点缀一些有礼貌的奉承（“请原谅，我只是要问一些问题以排除一些可能性。有一些可能很基础，请暂时忍受一下我...”）。 此刻，他没有再做任何铺垫，只是直接问：到底插电了没有？类似的问题会一直在自由软件邮件列表中被问起。目的不是冒犯接收者，而是快速排除大多数明显的（或许也是最常见的）解释。理解这种行为并作出响应的接收者会因为大度的态度获得成功。不能正确反应的接收者也不会受到谴责。这只是文化的冲突，不是某人的过错。要和蔼的解释你的问题（或批评）没有隐藏的含义；只是希望让（或传递）信息尽可能有效率，无他。

那么怎样是无礼？

详细的技术评论一种形式的谄媚，同理，如果不能提供高质量批评也可以看作是一种冒犯。我不是说仅仅忽略某人的工作，是提议、代码变更、新问题添加或任何事。除非您之前明确的承诺会有详细的反应，不做任何反应也没有错。人们只会假设你没有时间回答。但是如果你要反应，就要用心：花时间真的去分析，提供合适的实在例子，在以前的归档中发掘相关的文章等等。或者如果你没有时间花费这种精力，但仍需要写一些简短的回应，然后在信息中公开说明缺陷（“我知道有一个对应的问题，不过我没时间去搜索，对不起”）。主要是认识到文化标准的存在，通过履行承诺或公开的告知缺乏时间实现。无论何种方式，标准都会被加强。即使不能达到标准，不要在同一时间解释为什么你没有达到，这样做好像是说这个主题（以及那些参与者）不值得你花费时间。更好地是通过简洁而不是懒惰展示你的时间的价值。

也有一些其他形式的无礼，当然，但是大多数并不只存在于自由软件开发，而且常识足够引导你避免他们。如果你还没有看，可以看Chapter 2, 起步的the section called “防无礼于未然”。

面容

人脑中有一块专门负责识别面容的区域。它被非正式的称为“梭型面容区域”，其能力大多来自天生，而不是学习得到。因为识别单个人是至关重要的生存技巧，所以我们演化出了专门的硬件负责这个工作。

互联网基于的交流从心理上说有些古怪，因为需要许多无法用自然，原始的方法识别对方的人，进行紧密的合作：首先是面部识别，也有声音和姿势等。为了弥补这种不足，可以在所有地方使用一致的屏幕名称。他应该是你邮件地址的一部分（@之前的部分），你的IRC用户名，你的版本库提交名，你的问题跟踪用户名等等。这个名字就是你的在线“面容”：一段可以同你的真实面容起到同样效果的标识字符串，尽管他不是，但至少模拟了内置在电脑的硬件。。

屏幕名称应该是你真实姓名的直觉（例如我的是“kfogel”）展示。在一些情况中，会伴随你的完整名，例如在邮件头中：

From: "Karl Fogel" <kfogel@whateverdomain.com>

实际上，这个例子有两件事。就像前面提到的，屏幕名称用直觉方式匹配真实姓名。但是，真实姓名是真实的。而不是某种修饰的名称：

From: "Wonder Hacker" <wonderhacker@whateverdomain.com>

Paul Steiner有一副著名的卡通，刊登在1993年6月5日的纽约客，里面是一条狗登录到了电脑终端并阴险的与另一个人交谈：“在因特网上，没人知道你是一条狗。”这类思想的背后是自我夸大，这些有些俏皮的在线标识的人给了他们自己—好像被叫做“Wonder Hacker”就真的是神奇黑客了。但是事实没有改变：即使没人知道你是条狗，你还是条狗。一个幻想的在线标识不会打动读者。相反，他们会认为你只是形象而没有本体，或者仅仅是你是不安全的。在所有的交流中使用真实姓名，或者因为某些原因需要匿名，那么就请起一个完全像真名的名称，并一直用下去。

为了保持你的在线面容的一致，有一些方法可以让他更吸引人。如果你有正式的头衔（例如”博士“、”教授“和”导师“），不要炫耀，除非与对话内容相关，最好不要提及。作为一般的黑客之道，特别是自由软件文化，认为这些头衔是多余和不安全的标志（例如叫兽和砖家）。当然，如果这些头衔是作为标准的签名出现在每封邮件，不要把这个当作支持你在讨论中位置的工具—这种尝试必定事与愿违。你需要尊敬人的家伙，而不是尊敬这些头衔。

说到签名区：要保证短小有意义，或者更好的情况是没有签名区。避免大段的法律免责声明出现在每个邮件的结尾，特别是当他们表达的感情与自由软件项目的参与精神不匹配时。例如，如下是我参与的一个公开邮件列表中的某个用户每个文章都会出现的的经典流派：

IMPORTANT NOTICE

If you have received this e-mail in error or wish to read our e-mail
disclaimer statement and monitoring policy, please refer to the
statement below or contact the sender.

This communication is from Deloitte & Touche LLP.  Deloitte &
Touche LLP is a limited liability partnership registered in England
and Wales with registered number OC303675.  A list of members' names
is available for inspection at Stonecutter Court, 1 Stonecutter
Street, London EC4A 4TR, United Kingdom, the firm's principal place of
business and registered office.  Deloitte & Touche LLP is
authorised and regulated by the Financial Services Authority.

This communication and any attachments contain information which is
confidential and may also be privileged.  It is for the exclusive use
of the intended recipient(s).  If you are not the intended
recipient(s) please note that any form of disclosure, distribution,
copying or use of this communication or the information in it or in
any attachments is strictly prohibited and may be unlawful.  If you
have received this communication in error, please return it with the
title "received in error" to IT.SECURITY.UK@deloitte.co.uk then delete
the email and destroy any copies of it.

E-mail communications cannot be guaranteed to be secure or error free,
as information could be intercepted, corrupted, amended, lost,
destroyed, arrive late or incomplete, or contain viruses.  We do not
accept liability for any such matters or their consequences.  Anyone
who communicates with us by e-mail is taken to accept the risks in
doing so.

When addressed to our clients, any opinions or advice contained in
this e-mail and any attachments are subject to the terms and
conditions expressed in the governing Deloitte & Touche LLP client
engagement letter.

Opinions, conclusions and other information in this e-mail and any
attachments which do not relate to the official business of the firm
are neither given nor endorsed by it.

对于只想偶尔询问一个问题的人，如此巨大的免责声明虽然有点傻，但是没有任何永久的伤害。但是，如果某人希望活跃的参与到项目中，这个法律的陈词滥调会开始一个更潜在的影响。它会释放出两个潜在的破坏性的信号，这个人对于自己的工具没有完全的控制权力—他陷入了某个公司的邮件系统，这个系统会在每个邮件结尾添加讨厌的信息，而他无法绕过—其次，他对自己参与的自由软件活动只有有限或没有任何组织支持。诚然，组织明显没有禁止他在公共列表发表文章，但可以让他的文章看起来明显的不受欢迎，仿佛泄漏机密信息的风险必须排在第一位。

如果你所在的组织坚持对所有外发邮件添加这种签名区，应该考虑申请一个免费邮件帐号，例如，gmail.google.com、www.hotmail.com或www.yahoo.com，然后作为你在项目中的地址。

---

^[22] 关于这个主题有许多有趣的学术研究；例如Gutwin、Penner和Schneider所著的Group Awareness in Distributed Software Development。这篇论文曾经在网上出现过一段时间，之后消失，后来又在http://www.st.cs.uni-sb.de/edu/empirical-se/2006/PDFs/gutwin04.pdf再次出现。所以，如果这个地址无法访问，请通过搜索引擎搜索新地址。