# 寫下所有的內容 有時，項目中的許多廣為流傳的慣例和協定變得非常重要，你需要記錄下來。為了保證這種文檔的正統性，要清楚的表明這些內容基于郵件列表的討論，并已經形成協定開始生效。隨著你的編寫，應當引用郵件列表歸檔中的相關討論，對于任何不能確定的要點，要重新詢問并確認。文檔中不應當包含任何出其不意的東西：它不應當是協議的來源，而只是對于協議的描述。當然，如果它足夠成功，人們會開始引用它來作為自己權利的來源，但是這只是說明它精確的反映了團隊的整體意愿。 這是[Chapter?2, *起步*](# "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](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/how-it-works.html)和[http://www.apache.org/foundation/voting.html](http://www.apache.org/foundation/voting.html)。ASF是真正的一組軟件項目，合法的組織成一個非盈利公司，所以它的文檔傾向于描述管理程序，而不是開發慣例。他們也值得閱讀，因為他們代表了許多開源項目積累的經驗。