Author: cafonso Date: Thu Aug 23 13:01:19 2007 New Revision: 1077 Log: finished chap 04 first round
Modified: trunk/pt-pt/ch04.xml Modified: trunk/pt-pt/ch04.xml ============================================================================== --- trunk/pt-pt/ch04.xml (original) +++ trunk/pt-pt/ch04.xml Thu Aug 23 13:01:19 2007 @@ -549,91 +549,95 @@ <sect1 id="written-rules"> <title>Writing It All Down</title> -<para>At some point, the number of conventions and agreements floating -around in your project may become so great that you need to record it -somewhere. In order to give such a document legitimacy, make it clear -that it is based on mailing list discussions and on agreements already -in effect. As you compose it, refer to the relevant threads in the -mailing list archives, and whenever there's a point you're not sure -about, ask again. The document should not contain any surprises: it -is not the source of the agreements, it is merely a description of -them. Of course, if it is successful, people will start citing it as -a source of authority in itself, but that just means it reflects the -overall will of the group accurately.</para> - -<para>This is the document alluded to in <xref -linkend="developer-guidelines"/><phrase output="printed"> in -<xref linkend="getting-started"/></phrase>. Naturally, when the -project is very young, you will have to lay down guidelines without -the benefit of a long project history to draw on. But as the -development community matures, you can adjust the language to reflect -the way things actually turn out.</para> - -<para>Don't try to be comprehensive. No document can capture -everything people need to know about participating in a project. Many -of the conventions a project evolves remain forever unspoken, never -mentioned explicitly, yet adhered to by all. Other things are simply -too obvious to be mentioned, and would only distract from important -but non-obvious material. For example, there's no point writing -guidelines like "Be polite and respectful to others on the mailing -lists, and don't start flame wars," or "Write clean, readable bug-free -code." Of course these things are desirable, but since there's no -conceivable universe in which they might <emphasis>not</emphasis> be -desirable, they are not worth mentioning. If people are being rude on -the mailing list, or writing buggy code, they're not going to stop -just because the project guidelines said to. Such situations need to -be dealt with as they arise, not by blanket admonitions to be good. -On the other hand, if the project has specific guidelines about -<emphasis>how</emphasis> to write good code, such as rules about -documenting every API in a certain format, then those guidelines -should be written down as completely as possible.</para> - -<para>A good way to determine what to include is to base the document -on the questions that newcomers ask most often, and on the complaints -experienced developers make most often. This doesn't necessarily mean -it should turn into a FAQ sheet—it probably needs a more -coherent narrative structure than FAQs can offer. But it should -follow the same reality-based principle of addressing the issues that -actually arise, rather than those you anticipate might arise.</para> - -<para>If the project is a benevolent dictatorship, or has officers -endowed with special powers (president, chair, whatever), then the -document is also a good opportunity to codify succession procedures. -Sometimes this can be as simple as naming specific people as -replacements in case the BD suddenly leaves the project for any -reason. Generally, if there is a BD, only the BD can get away with -naming a successor. If there are elected officers, then the -nomination and election procedure that was used to choose them in the -first place should be described in the document. If there was no -procedure originally, then get consensus on a procedure on the mailing -lists <emphasis>before</emphasis> writing about it. People can -sometimes be touchy about hierarchical structures, so the subject -needs to be approached with sensitivity.</para> - -<para>Perhaps the most important thing is to make it clear that the -rules can be reconsidered. If the conventions described in the -document start to hamper the project, remind everyone that it is -supposed to be a living reflection of the group's intentions, not a -source of frustration and blockage. If someone makes a habit of -inappropriately asking for rules to be reconsidered every time the -rules get in her way, you don't always need to debate it with -her—sometimes silence is the best tactic. If other people -agree with the complaints, they'll chime in, and it will be obvious -that something needs to change. If no one else agrees, then the -person won't get much response, and the rules will stay as they -are.</para> - -<para>Two good examples of project guidelines are the Subversion -<filename>hacking.html</filename> file, at <ulink -url="http://svn.collab.net/repos/svn/trunk/www/hacking.html"/>, and the Apache -Software Foundation governance documents, at <ulink +<para>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 reflete o entendimento geral do grupo de forma +correcta.</para> + +<para>É este o documento a que se alude em <xref +linkend="developer-guidelines"/><phrase output="printed"> em +<xref linkend="getting-started"/></phrase>. 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 refletir a forma que as coisas realmente tomaram.</para> + +<para>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 respete os outra na lista de distribuição +de correio e não inicie uma guerra inflamada", ou "Escreva código limpor, +legível e sem erros". Claro que isto é desejável mas visto não haver +um universos onde elas possam <emphasis>não</emphasis> 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 +<emphasis>como</emphasis> 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.</para> + +<para>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.</para> + +<para>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 especificas +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 <emphasis>antes</emphasis> 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.</para> + +<para>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..</para> + +<para>Dois bons exemplos de directrizes de projectos são o ficheiro do + Subversion <filename>hacking.html</filename> em <ulink +url="http://svn.collab.net/repos/svn/trunk/www/hacking.html"/>, e os +documentos sobre governo da Apache Software Foundation em <ulink url="http://www.apache.org/foundation/how-it-works.html"/> and <ulink -url="http://www.apache.org/foundation/voting.html"/>. The ASF is -really a collection of software projects, legally organized as a -nonprofit corporation, so its documents tend to describe governance -procedures more than development conventions. They're still worth -reading, though, because they represent the accumulated experience of -a lot of open source projects.</para> +url="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.</para> </sect1> _______________________________________________ Producingoss-translators mailing list [email protected] http://www.red-bean.com/mailman/listinfo/producingoss-translators
