Question

有时，项目中的许多广为流传的惯例和协定变得非常重要，你需要记录下来。为了保证这种文档的正统性，要清楚的表明这些内容基于邮件列表的讨论，并已经形成协定开始生效。随着你的编写，应当引用邮件列表归档中的相关讨论，对于任何不能确定的要点，要重新询问并确认。文档中不应当包含任何出其不意的东西：它不应当是协议的来源，而只是对于协议的描述。当然，如果它足够成功，人们会开始引用它来作为自己权利的来源，但是这只是说明它精确的反映了团队的整体意愿。

这是Chapter 2, 起步的the section called “开发者指南”暗示的文档。当然，当项目还非常年轻时，你无法依靠项目的历史来规划指导方针。但是随着开发社区的成熟，你可以调整这些语言以反映实际的内容。

不要尝试全面。没有文档能够涵盖参与一个项目所需的所有事情。许多项目演进出的习惯是永远不会说出来的，永远不会明确提出来，即使是所有人遵循的。还有一些内容则明显太过简单，无需提及，只会分散人们对于重要内容的注意力。例如，没有必要写下指导方针如“在邮件列表中要有礼貌，要互相尊重，不要激烈的争论”或“要写清楚的、可读的和无bug的代码。”当然，这些事情都是人们希望的，但是因为没有想像到他们可能不会渴望得到的东西，所以没有价值去提及。如果人们在邮件列表中过于粗暴，或编写了充满bug的代码，不会因为项目指导方针没有说，他们就会继续下去。这种情形出现时就会需要被处理，不会因为预先的劝诫就会好起来。另一方面，如果项目有关于如何写好代码的指导方针，例如关于使用何种格式记录API的规则，那么这个指导方针就应该尽可能的写完整。

决定将什么内容纳入文档的最好方法是以新来者所经常询问的问题，以及资深开发者最经常的抱怨为基础。这不是说一定要变成一个FAQ表单—很可能需要一个比FAQ所能提供的更连贯的叙述结构。但是它必须遵循事实为根据的原理，记录问题实际发生的地址，而不是好像你预期会出现。

如果项目是一个慈善独裁者所有，或者有拥有特殊权利的官员（总裁、主席或其他），那么继任程序也应当制定成法律形成文档。有时候，这仅仅是BD因故突然离开项目并简单的指定继任者。通常情况下，如果有一个BD，那么只有BD可以离开并提名继任者。如果有竞选的成员，那么文档就应该描述从中取出第一名的提名和选举程序。如果原来没有程序，那么在编写前应该在邮件列表中达成共识。人们有时候可能对于等级结构十分敏感，所以主题应当敏感的达到这个目标。

可能最重要的事情是表明规则是可以商量的。如果文档中规定的习惯变得束缚了项目，要让每个人想到这是一种对于团队意愿的生动反映，而不是挫折和堵塞的来源。如果某人养成了每当遇到妨碍自己的规则都要求重新考虑规则的习惯时，你不需要一直与其辩论—有时候沉默是最好的策略。如果其他人认可这种抱怨，他们会插话，也就是意味着某些事情很明显需要改变了。如果没有其他人认可，人们就不太会响应，那规则还是会保持不变。

两个指导方针的好例子是Subversion的hacking.html文件，在http://svn.collab.net/repos/svn/trunk/www/hacking.html，以及Apache软件基金会管理的文档，在http://www.apache.org/foundation/how-it-works.html和http://www.apache.org/foundation/voting.html。ASF是真正的一组软件项目，合法的组织成一个非盈利公司，所以它的文档倾向于描述管理程序，而不是开发惯例。他们也值得阅读，因为他们代表了许多开源项目积累的经验。