A un certo punto il numero degli accordi e delle convenzioni che girano nel vostro progetto diventa talmente grande che avete bisogno di registrarli da qualche parte. Per dare una tale legittimazione documentale, chiarite che essa è basata sulle discussioni della mailing list e sugli accordi già effettivi. Quando componete il documento, fate riferimento alle discussioni rilevanti negli archivi della mailing list, e dove c'è un punto di cui non siete sicuri, chiedete. Il documento non deve contenere sorprese: esso non è la fonte di accordi, esso è solamente la loro descrizione. Certamente, se ha successo, la gente incomincerà a citarlo come una fonte di autorità in se stesso, ma ciò significa appunto che esso riflette la volontà generale del gruppo accuratamente.

Questo è il documento a cui si allude in sezione chiamata «Linee Guida per lo Sviluppatore» in Capitolo 2, Partenza. Naturalmente, quando il progetto è molto giovane, avrete da mettere giù linee guida senza il beneficio di una lunga storia del progetto da cui trarre ispirazione. Ma appena la comunità di sviluppo matura, potete adattare il linguaggio per rispecchiare le cose che via via vengono fuori.

Non cercate di essere completi. Nessun documento può contenere ogni cosa che la gente ha bisogno di sapere sulla partecipazione al progetto. Molte delle convenzioni che il progetto elabora rimangono per sempre non dette, mai menzionate esplicitamente, eppure accolte da tutti. Altre cose sono semplicemente troppo ovvie per essere menzionate, e solamente distrarrebbero dall'importante, ma non ovvio materiale. Per esempio non ha senso scrivere linee guida come “Siate puliti e rispettosi verso gli altri nella mailing list e non incominciate guerre di offese,” o “scrivete un codice chiaro, leggibile e libero da bugs”. Certamente queste cose sono desiderabili, ma poiché non c'è universo concepibile in cui esse potrebbero non essere desiderabili non vale la pena menzionarle. Se la gente è ruvida nella mailing list, o scrivere codice con bugs, essi non si fermeranno perché lo hanno detto le linee guida del progetto. C'è bisogno che queste situazioni siano affrontate quando nascono, non con ammonizioni generali ad essere buoni. D'altra parte se il progetto ha delle linee guida specifiche su come scrivere buon codice come le regole per documentare le API in un certo formato, allora queste linee guida devono essere messe giù nella maniera più completa possibile.

Una buona maniera per individuare cosa includervi, è basare il documento sulle domande che i nuovi arrivati fanno più spesso e sulle lamentele più frequenti degli sviluppatori. Questo non significa necessariamente che ciò dovrebbe finire nel foglio delle FAQ —probabilmente ciò ha bisogno di una struttura più narrativa di quanto le FAQ possano offrire; ma essa dovrebbe seguire lo stesso principio basato sul reale di dare un indirizzo ai problemi che realmente sorgono, piuttosto che quelli che voi anticipate possano sorgere.

Se il progetto è una benevola dittatura, o ha funzionari investiti di speciali poteri (presidente, poltrona, qualcos'altro), allora il documento è una buona opportunità di codificare le procedure di successione. A volte questo può essere semplice come nominare specifiche persone come sostituti nel caso che il BD lasci il improvvisamente il progetto per qualche ragione. Generalmente, se c'è un BD, solo il BD può andarsene nominando un successore. Se ci sono funzionari per elezione, allora la procedura di elezione e di nomina che è stata usata per sceglierli in primo luogo dovrebbe essere descritta nel documento. Se non c'era nessuna procedura all'origine, allora ottenete il consenso sulla procedura nella mailing list prima di scriverla. La gente a volte può essere permalosa con le strutture gerarchiche, così il soggetto bisogna prenderlo con tatto.

Forse la cosa più importante è chiarire che i ruoli possono essere riconsiderati. Se le convenzioni descritte nel documento incominciano ad ostacolare il progetto, ricordate a tutti che si suppone che ci sia una viva riflessione delle intenzioni del gruppo, non un sorta di frustrazione o di blocco. Se qualcuno ha il vizio di chiedere inappropriatamente che le regole vengano riconsiderate ogni volta che le regole vanno a suo modo, voi non dovete discutere ciò con lui—a volte il silenzio è la miglior tattica. Se altre persone si aggiungono alla protesta, suoneranno insieme, e sarà ovvio che qualcosa bisogna cambiarla. Se nessuna altro si aggiunge, allora la persona non raccoglierà molto consenso e le cose resteranno così come sono.

Due buoni esempi di linee guida di un progetto sono il Subversion hacking.html file, a http://subversion.apache.org/docs/community-guide/, a e i documenti dell'amministrazione dell'Apache Software Foundation, a http://www.apache.org/foundation/how-it-works.html e http://www.apache.org/foundation/voting.html. La ASF in realtà è un insieme di progetti di software, legalmente organizzata come una organizzazione no profit, così i suoi documenti tendono a descrivere le procedure di organizzazione, più che le convenzioni di sviluppo. Esse sono anche letture di pregio, tuttavia, perché rappresentano l'esperienza accumulata di un gran numero di progetti open source.