Nalgum ponto o número de convenções e acordos a voar no vosso projecto pode tornar-se de tal modo elevado que necessitará registá-los em algum lugar. De modo a dar alguma legitimidade a um tal documento, deixe claro que se baseia nas discussões da lista de distribuição de correio e acordos já efectivos. Há medida que o vai escrevendo refira-se aos ramos relevantes dos arquivos da lista de distribuição de correio, e sempre que haja um ponto sobre o qual não tenha a certeza absoluta pergunte novamente. O documento não deve conter qualquer surpresa: não é origem de acordos é uma mera descrição de acordos. Claro que se for bem sucedido as pessoas começam a citá-lo como origem com autoridade, mas isso só significa que reflecte o entendimento geral do grupo de forma correcta.

É este o documento a que se alude em “Developer Guidelines” em Capítulo 2, Getting Started. Naturalmente quando o projecto é muito novo, terá que estabelecer directrizes sem a vantagem que a história longa de um projecto traz. Mas à medida que a comunidade que o desenvolve amadurece, pode ajustar a linguagem para reflectir a forma que as coisas realmente tomaram.

Não tente ser exaustivo. Nenhum documento pode capturar tudo o que as pessoas necessitam saber sobre como participar num projecto. Muitas das convenções de um projecto que progride ficam para sempre não ditas, nem nunca são mencionadas de modo explícito e, no entanto, todos aderem às mesmas. Outras coisas são simplesmente demasiado óbvias para serem mencionadas, e distrairiam de material importante mas não óbvio. Por exemplo não há razão para escrever directrizes equivalentes a "Seja educado e respeite os outra na lista de distribuição de correio e não inicie uma guerra inflamada", ou "Escreva código claro, legível e sem erros". Claro que isto é desejável mas visto não haver um universos onde elas possam não ser desejáveis, não vale a pena mencionar. Se as pessoas estão a ser agrestes na lista de distribuição de correio, ou a escrever código com erros nada as irá fazer parar devido só a que as directrizes do projecto o digam. Tais situações necessitam de ser tratadas quando são levantadas, mas não com admoestações para ser bonzinho. Por outro lado se o projecto tiver directrizes sobre como escrever bom código, tais como regras para documentar as API num certo formato, então essas directrizes devem ser escritas de modo tão completo quanto possível.

Um boa maneira de determinar o que incluir é basear o documento nas perguntas efectuadas mais frequentemente pelos novatos e nas queixas que os programadores mais experientes fazem. Isto não significa necessariamente que se deve tornar numa FAQ —provavelmente necessita de uma estrutura narrativa mais coerente do que a dada pelas FAQ. Mas deve seguir o mesmo princípio de estar baseada na realidade de tratar os temas que de facto são levantados em vez daqueles que antecipe que venham a ser levantados.

Se o projecto é uma ditadura benevolente, ou tem funcionários com poderes especiais (presidente, ...), então o documento é uma boa oportunidade para codificar os procedimentos de sucessão. Isto por vezes pode ser tão simples quanto nomear pessoas específicas como substitutos no caso de uma saída repentina do projecto do BD por qualquer razão. Geralmente, se há um BD, só o BD pode nomear um sucessor. Se os funcionários forem eleitos então o processo de nomeação e eleição que foi usado para os escolher em primeiro lugar deve ser descrito no documento. Se não houver originalmente um procedimento então trate de obter consenso sobre um procedimento na lista de distribuição de correio antes de escrever sobre isso. As pessoas podem por vezes ser sensíveis sobre as estruturas hierárquicas, e assim sendo o tema necessita de ser tratado com sensibilidade.

Talvez seja mais importante tornar claro que as regras podem ser reapreciadas. Se as convenções descritas no documento começarem a atrazar o projecto, lembre que é suposto ser uma reflexão viva das intenções do grupo e não uma fonte de frustração e bloqueio. Se alguém fizer hábito de inapropriadamente pedir que as regras sejam reconsideradas de cada vez que as regras lhes apareçam ao caminho não necessita de debater isso com elas —por vezes o silêncio é a melhor táctica. Se houver mais gente a concordar com as reclamações, elas trataram de avançar, e será óbvio que algo necessita de ser mudado. Se ninguém mais concordar então a pessoa não terá muitos seguidores e as regras irão manter-se tal como estão..

Dois bons exemplos de directrizes de projectos são o ficheiro do Subversion hacking.html em http://subversion.apache.org/docs/community-guide/, e os documentos sobre governo da Apache Software Foundation em http://www.apache.org/foundation/how-it-works.html e http://www.apache.org/foundation/voting.html. A ASF de facto é uma coleção de projectos de software, legalmente organizados como uma corporação sem fins lucrativos, e assim os seus documentos tendem a descrever mais procedimentos de governo que convenções de desenvolvimento. Mesmo assim é bom ler, pois representam a experiência acumulada de muitos projectos de «open source».