Índice
O modelo tradicional de como os projetos de software livre iniciam foram disponibilizados por Eric Raymond, em um ensaio que agora está famoso nos processos de código aberto com o título A Catedral e o Bazar. Ele escreveu:
Todo bom trabalho de software começa ao se colocar o dedo na ferida de um programador.
(retirado de http://www.catb.org/~esr/writings/cathedral-bazaar/ )
Note que Raymond não estava dizendo que os projetos de código aberto acontecem somente quando um indivíduo tem uma "ferida". Melhor, ele esta dizendo que um bom software acontece quando o programador tem um interesse pessoal em ver o problema resolvido; a relevância disso para o software livre era que a "ferida" pessoal calhou de ser a motivação mais frequênte para iniciar um projeto de software livre.
Isto ainda é como a maioria dos projetos são iniciados, mas menos agora que em 1997, quando Raymond escreveu estas palavras. Hoje, temos o fenômeno das organizações—incluindo as empresas que visam lucro—iniciando do zero grandes projetos de código aberto e com gerenciamento centralizado. O programador solitário, desenvolvendo algum código para resolver um problema local, percebendo, então, que o resultado tem uma aplicabilidade mais vasta, ainda é a fonte de muito software livre novo, mas essa não é a única história.
De qualquer forma, a evidência de Raymond ainda é perspicaz. A condição principal é que os produtores do software tenham um interesse direto em seu sucesso, porque eles próprios o utilizam. Se o software não faz o que deveria fazer, a pessoa ou organização que está produzindo-o sentirá a insatisfação em seu trabalho diário. Por exemplo, o projeto OpenAdapter (http://www.openadapter.org/), o qual foi iniciado por investimento do banco Dresdner Kleinwort Wasserstein como um framework de código aberto para integrar diferentes sistemas de informação financeira, pode dificilmente ser dito como por o dedo na ferida pessoal de qualquer programador individual. Isso põe o dedo na ferida de uma instituição. Mas essa ferida surge diretamente das experiências da instituição e de seus parceiros e, por esse motivo, se o projeto falha em aliviá-los, eles reconhecerão. Essa combinação produz um bom software porque o laço de feedback flui na direção certa. O programa não está sendo escrito para ser vendido a outros, para tentarem resolver seus problemas. Ele está sendo escrito para resolver os próprios problemas de alguém e, então, poder ser compartilhado com todos. Em suma, podemos comparar o problema a uma doença e o software a um medicamento cuja distribuição destina-se a erradicar completamente a epidemia.
Este capítulo fala sobre como introduzir um novo projeto de software livre ao mundo, mas muitas dessas recomendações soariam familiar a uma organização de saúde distribuindo medicamentos. Os objetivos são bem similares: você quer deixar bem claro o que o medicamento faz, distribuí-lo nas mãos das pessoas certas, tendo certeza de que aqueles que o receberam sabem como utilizá-lo. Mas com software, você também quer atrair alguns dos destinatários para participarem da pesquisa em andamento com empenho para aperfeiçoarem o "medicamento".
A distribuição de Software Livre é uma tarefa duplicada. O software necessita adquirir usuários, e adquirir desenvolvedores. Essas duas necessidades não estão necessariamente em conflito, mas elas adicionam um pouco de complexidade a apresentação inicial do projeto. Algumas informações são úteis para ambas audiências, algumas são úteis somente para uma ou a outra. Ambos tipos de informações deveriam contribuir para o princípio de apresentação escalada; isto é, o grau de detalhes apresentados em cada estágio deveria corresponder diretamente a quantidade de tempo e esforço encaixados pelo leitor. Mais esforço deveria sempre igualar a mais contribuição. Quando os dois não se correlacionam firmimente, as pessoas podem rapidamente perder a fé no projeto e pararem de investir esforços.
A consequência evidente disso é que aparência importa. Programadores, em particular, frequentemente não gostam de acreditar nisso. Seu amor pelo conteúdo sobre a forma é quase um ponto de orgulho profissional. Não é por acaso que tantos programadores demonstram antipatia por trabalhos de marketing e relações públicas, nem que designers gráficos profissionais ficam frequentemente horrorizados com o que os programadores desenham por eles mesmos.
Isso é uma pena, porque existem situações onde a forma é conteúdo, e a aprensentação do projeto é uma delas. Por exemplo, a primeira coisa que um visitante absorve sobre um projeto é a aparência de seu web site. Esta informação é absorvida antes que qualquer conteúdo possa ser compreendido—antes de que qualquer texto tenha sido lido ou que links tenham sido clicados. No entanto, isto pode ser injusto, mas as pessoas sempre vão formar uma primeira impressão imediata. A aparência de um site mostra sinais dos cuidados que foram tomados na apresentação de um projeto. Humanos tem "antenas" extremamente sensíveis em detectar o cuidado investido. A maioria de nós pode falar em um relance se um site foi feito as pressas ou se foi seriamente pensado. Este é o primeiro contato que seu projeto expõe, e a impressão que isso cria será levada para o resto do projeto, por associação.
Assim, enquanto muito deste capítulo fala sobre o conteúdo com o qual o seu projeto deve começar, lembre-se que sua aparência e o que ele passa também importam. Como o web site do projeto deve funcionar para dois diferentes tipos de visitantes—usuários e desenvolvedores—uma atenção especial deve ser tomada para dar clareza e direcionamento. Apesar de não ser o local para tratar de web design, um princícpio é importante o suficiente para merecer ser falado, particularmente quando um site atende a muitos públicos: as pessoas deveriam ter uma forte ideia para onde um link vai antes de clicar nele. Por exemplo, deveria ser óbvio, olhando para os links de documentação do usuário, saber que eles o levarão para a documentação do usuário, e não para, digamos, a documentação do desenvolvedor. A execução de um projeto deve, em parte, fornecer informação, mas deve também fornecer conforto. A mera presença de certas ofertas padrões, nos lugares esperados, tranquiliza usuários e desenvolvedores que estão decidindo em se envolver. Essas ofertas dizem que o projeto mantém suas ações em união, que disponibilizam perguntas frequentes, antecipadamente, e que estas foram respondidas de forma a requerer o mínimo de esforço de quem pergunta. Por dar esta sensação de preparação, o projeto dá a mensagem: "O seu tempo não será perdido se você participar", o que é exatamente o que as pessoas esperam ouvir.
Antes de iniciar um projeto de código aberto, existe uma advertência importante:
Sempre olhe em volta para ver se existe um projeto que faz o que você quer. As chances são boas para qualquer problema que você queira resolver agora, alguma outra pessoa quis resolver antes de você. Se eles não resolveram, e lançaram o código sob uma licença livre, então não há razão para você reinventar a roda hoje. Claro que existem exceções: se você quer iniciar um projeto como uma experiência educacional, um código já existente não irá ajudar; ou talvez o projeto que você tem em mente é tão específico que você sabe que não há chances de alguém ter desenvolvido isso. Mas geralmente, não há motivos para não procurar, e a lista pode ser enorme. Se os mecanismos de buscas usuais não mostrarem nada, tente procurar em http://freshmeat.net/ (um site de notícias de projetos de código aberto, o qual será falado mais tarde), em http://www.sourceforge.net/, e na Free Software Foundation, directório de software livre em http://directory.fsf.org/.
Mesmo se você não achar exatamente o que você está procurando, você pode encontrar algo muito próximo que pode fazer mais sentido se unir aquele projeto e adicionar a funcionalidade que iniciar do zero você mesmo.
Você olhou em volta, e não encontrou nada que realmente atendesse suas necessidades, e decidiu iniciar um novo projeto.
E agora?
A parte mais difícil em lançar um projeto de software livre é transformar a visão privada em pública. Você ou a sua organização poder saber perfeitamente bem o que querem, mas expressar este objetivo de maneira compreensiva ao mundo é um belo trabalho. É essencial, entretanto, que você reserve algum tempo para faze-lo. Voce e os outros fundadores devem decidir sobre do que realmente se trata o projeto—isto é, decidir suas limitações, o que ele não fará assim como o que ele fará—e escrever uma declaração de missçao. Esta é a parte geralmente não é tão difícil, embora ela possa algumas vezes revelar suposições implícitas e até desacordos em relação a natureza do projeto, o que é bom: melhor resolve-los agora do que mais tarde. O próximo passo é o pacote do projeto para uso público, e isso é, basicamente, pura labuta.
O que faz isso tão trabalhoso é que consiste principalmente
em organizar e documentar o que todo mundo já sabe—"todo mundo",
ou seja, quem está envolvido com o projeto até o momento. Assim,
para o pessoal que está trabalhando no projeto, não há um benefício
imediato. Eles não precisam de um arquivo LEIAME
com a visão geral do projeto, nem um documento de design ou manual
do usuário. Eles não precisam de uma árvore de código cuidadosamente
formatada conforme os padrões informais mas largamente difundidos de
distribuição de fontes de software. De qualquer forma que o código
estiver disponível está bom para eles, porque eles já estão acostumados
com isso mesmo, e se o código executa completamente, eles sabem como
usá-lo. Nem mesmo importa a eles, se os pressupostos de arquitetura
fundamentais do projeto fiquem sem documentação; eles já estão
familiarizados com isso também.
Os recém-chegados, por outro lado, precisam destes documentos. Felizmente, eles não precisam de todos de uma vez. Não é necessário que você forneça todos os recursos necessários antes de tornar o projeto público. Em um mundo perfeito, talvez, todo novo projeto de código aberto poderia começar seu ciclo de vida com um documento completo de design, um manual completo de usuário (com marcações especiais para funcionalidades planejadas mas não documentadas), com um pacote de código lindo e portável, capaz de executar em qualquer plataforma de computador, e assim por diante. Na realidade, cuidade de todos estes pontos seria exageradamente demorado, e de qualquer forma, é um trabalho que pode-se razoavelmente esperar que os voluntários irão ajudar uma vez que o projeto esteja em andamento.
O que é necessario, entretanto, é o investimento colocado na apresentação que os recém-chegados possam passar pelo obstáculo inicial da falta de familiaridade. Pense nisso como se fosse a primeira etapa em um processo de boot, que traz ao projeto um forma mínima de ativação de energia. Tenho ouvido esta definição de energia de hacktivação: o esforço mínimo de um recém-chegado precisa fazer antes de ter algo em retorno. Quanto menor a energia de hacktivação, melhor. Sua primeira tarefa é diminuir a energia de hacktivação a um nível que encoraje as pessoas a se envolverem com o projeto.
Cada uma das seguintes subseções descreve um aspecto importante para iniciar um novo projeto. Eles são apresentadas aproximadamente na ordem em que um visitante poderia encontra-las, embora é claro que a ordem do qual você vai realmente implementa-las pode ser diferente. Você pode considerá-las como um checklist. Quando iniciar um projeto, verifique a lista e certifique-se que você cobriu cada item, ou que pelo menos que você está confortável com as potenciais consequencias de deixar algum de fora.
Ponha-se no lugar de alguém que tenha acabado de ouvir sobre seu projeto, talvez por ter topado com ele enquando realizava uma busca por um software para solucionar algum problema. A primeira coisa que eles irão encontrar será o nome do projeto.
Um bom nome não irá automaticamente fazer do seu projeto um sucesso, e um nome ruim não irá destruí-lo—bom, um nome realmente ruim provavelmente poderia fazer isso, mas vamos assumir que ninguém está tentando ativamente fazer com que seu projeto seja um fracasso. No entanto, um nome ruim pode desacelerar a adoção ao projeto, ou por que as pessoas não o levarão a sério, ou porque eles simplesmente terão problemas para lembrarem-se dele.
Um bom nome:
Traz a ideia do que o projeto faz, ou ao menos está relacionado de maneira óbvia, de forma que se alguém sabe o nome e sabe o que o projeto faz, daí em diante o nome virá rapidamente a cabeça.
É fácil de lembrar. Aqui, não há como contornar o fato de que o inglês se tornou a linguagem padrão da Internet: "fácil de lembrar" significa "facil para alguem que possa ler em inglês de lembrar." Nomes que são trocadilhos dependentes da pronunciação de um nativo, por exemplo, irão ser opacos para muitos leitores de inglês não-nativos por aí. Se o trocadilho é particulamente convincente e memorável, ele ainda pode valer a pena; apenas tenha em mente que muitas pessoas olhando o nome não irão ouvi-lo em suas cabecas da maneira que um nativo ouviria.
Não é o mesmo que outros nomes de projeto, e não viola nenhuma marca. Estas são apenas boas maneiras, assim como bom senso legal. Você não quer criar uma confusão de identidade. É difícil estar por dentro de tudo o que já está disponível Net, sem que coisas diferentes tenham o mesmo nome.
Os recursos mencionados antes em “Mas primeiro, olhe em volta” são úteis em descobrir se outro projeto já tem o nome ao qual você está pensando. A busca de marcas livres estão disponível em http://www.nameprotect.org/ e http://www.uspto.gov/.
Se possível, está disponível os nomes de domínio em
.com,
.net, e
.org.
Você deve escolher um, provavelmente o .org,
para manter como o web site oficial para o projeto;
os outros dois devem redirecionar para lá e são simplesmente
para evitar que terceiros criem alguma confusão de identidade
ao redor do nome do projeto. Mesmo que você pretenda hospedar
o projeto em outro site (veja “Hospedagem enlatada”),
você ainda pode registrar os domínios específicos para o
projeto e redirecioná-los para o site em que ele está hospedado.
Isso ajuda muito os usuários a terem uma URL simples para
lembrar.
Uma vez que eles tenha encnotrado o web site, a próxima coisa que irão procurar é uma breve descrição, uma declaração de missão, aí eles poderão decidir (dentro de 30 segundos) se eles estão ou não interessados em saber mais. Ela deve ser proeminentemente colocada na página de rosto, preferencialmente logo após o nome do projeto.
A declaração de missão deve ser concreta, limitada, e acima de tudo, curta. Aqui está um exemplo de uma boa declaração, retirada de http://www.openoffice.org/:
Para criar, como uma comunidade, a suíte office líder internacionalmente que irá rodar sobre todas as plataformas principais e fornecer acesso a todas as funcionalidades e dados através de um componente aberto baseado em APIs e formato de arquivos baseado em XML.
Em apenas algumas palavras, eles atingiram todos os pontos altos, principalmente baseando-se em um conhecimento prévio do leitor. Ao citar "como uma comunidade", eles sinalizam que nenhuma empresa irá dominar o desenvolvimento; "internacionalmente" significa que o software irá permitir que as pessoas trabalhem em diversas linguagens e locais; "todas as plataformas principais" significa que ele será portável para Unix, Macintosh, e Windoes. O restante sinaliza que interfaces abertas e formatos de arquivo de fácil compreensão são aspectos importantes do objetivo. Eles não vêm a público dizendo que estão tentando ser uma alternative livre ao Microsoft Office, mas a maioria das pessoas podem ler nas entrelinhas. Embora esta declaração de missão pareça ampla a primeira vista, na verdade ela é bem circunscrita: as palavras "suíte office" significa algo muito concreto para os que estão familiarizados com tal software. Mais uma vez, o presumido conhecimento prévio do leitor (neste caso provavelmente oriundo do MS Office) é usado para manter a declaração de missão concisa.
A natureza da declaração de missão depende parcialmente de quem a está escrevendo, não apenas no software que ele descreve. Por exemplo, faz sentido para OpenOffice.org usar as palavras "como uma comunidade", por que o projeto foi iniciado, e ainda é amplamente patrocinado pela Oracle[11] Por incluir estas palavras, a Oracle indica sua sensibilidade em preocupações que poderiam dominar o processo de desenvolvimento, apenas demonstrando consciência do potencial de virar um problema e ter um longo caminho para evitar o problema completamente. Por outro lado, projetos que não são patrocinados por uma única empresa provavelmente não necessita de tais argumentos; afinal de contas, desenvolvimento pela comunidade é a regra, o que normalmente não seria razão para listá-la como parte da missão.
Aqueles que continuarem interessados após lerem a declaração de missão irão querer olhar mais detalher, talvez alguma documentação de usuário ou desenvolvedorl, e eventualmente irão fazer o download de algo. Mas antes disso, eles irão se certificar que é um projeto de código aberto.
A página inicial deve ter de forma muito clara que o projeto é de código aberto. Isso pode parecer óbvio, mas você ficaria surpreso de quantos projetos esquecem de fazer isto. Eu vi web sites de projetos de software livre onde na páginal inicial não somente não dizia sob qual o tipo de licença o software era distribuído, mas nem mesmo declarava que o software era livre. Algumas vezes este pequeno detalhe de informação crucial era visível apenas na página de Download, ou na página de Desenvolvedores, ou qualquer outro lugar onde era preciso mais um clique do mouse para chegar até lá. Em casos extremos, a licença não era mencionada em nenhum local do web site—a única maneira para encontrá-la era realizar o download do software e procurar dentro dele.
Não cometa este erro. Tal omissão pode deixar escapar muitos potenciais desenvolvedores e usuários. Declare de cara, logo abaixo a declaração de missão, que o projeto é um "software livre" ou "software de código aberto", e forneça a licença exata. Um guia rápido para escolha da licença é dado em “Escolhendo a Licença e Aplicando-a” mais adiante neste capítulo, e os problemas de licenciamento são discutidos em detalhes no Capítulo 9, Licenses, Copyrights, and Patents.
Neste ponto, nosso visitante hipotético determinou— provavelmente em um minuto ou menos—que ele está interessado em passar, digamos, pelo menos mais cinco minutos investigando este projeto. As próximas seções descrevem o que ele poderá encontrar nestes cinco minutos.
Deve existir uma breve lista de funcionalidades suportadas pelo software (se algo ainda não está completo, você ainda pode listá-lo, mas coloque "planejado" ou "em andamento" prómimo a ele), e o tipo de ambiente computacional necessário para executar o software. Pense na lista de funcionalidades/requerimentos como a que você daria a alguém que perguta por um resumo do software. Isso é geralmente apenas uma expansão lógica da declaração de missão. Por exemplo, a declaração de missão pode ser:
Criar um indexador completo de texto e motor de busca com uma API rica, para uso de programadores proveem serviços de busca para uma vasta coleção de arquivos de texto.
A lista de funcionalidade e requerimentos daria os detalhes, clareando o escopo da declaração de missão:
Funcionalidades:
Procura por textos puros, HTML, e XML
Busca por palavra ou frases
(planejado) correspondências Fuzzy
(planejado) Atualização incremental de índices
(planejado) Indexação de web sites remotos
Requerimentos:
Python 2.2 ou superior
Espaço em disco suficiente para armazenar os índices (aproximadamento 2x o tamanho original do dado)
Com esta informação, os leitores podem rapidamente saber se este software tem chances de funcionar para eles, e podem consider em participarem também como desenvolvedores.
As pessoas sempre querem saber como está indo um projeto. Para novos projetos, eles querem saber o gap entre a promessa do projeto e a atual realidade. Para projetor mais maduros, eles querem saber quanto que ele é ativamente mantido, a fequencia de novos lançamentos, a resposta para reportes de bug, etc.
Para responder a estas questões, você deve fornecer uma página de status de desenvolvimento, listando os objetivos a curto prazo do projeto e necessidades (por exemplo, ele pode estar precisando de desenvolvedores com um tipo específico de experiência). A página pode também mostrar um histórico de versões anteriores, com a lista de funcionalidades, para que visitantes possam ter uma ideia de como o projeto define "progresso" e a velocidade com que esse progresso ocorre de acordo com esta definição.
Não tenha medo de parecer despreparado, e não caia na tentação de exagerar no status de desenvolvimento. Todo mundo sabe que o software evolui por estágios; não há vergonha em dizer "Este é um software na versão alpha com alguns bugs conhecidos". Ele roda, e funciona ao menos por um tempo, mas use-o por sua conta e risco." Tal linguagem não espantará os tipos de desenvolvedores que você precisa neste estágio. Quanto aos usuários, uma das piores coisas que um projeto pode fazer é atrir usuários antes do software estar pronto para eles. Uma reputação de instabilidade ou excesso de bugs é difícil de eliminar, uma vez adquirida. O conservadorismo compensa a longo prazo; é sempre melhor para o software ser mais estável que o esperado para o usuário do que menos, e surpresas agradáveis produzem o melhor tipo de boca a boca.
O software deve estar disponível para download em código fonte em um formato padrão. Quando um projeto está dando os primeiros passos, o pacote binário (executável) não é necessário, a menos que o software tenha requisitos de construção ou dependências tão complicadas que somente para exetutar daria muito trabalho para a maioria das pessoas. (Mas se este é o caso, de qualquer forma o projeto terá uma fase difícil para atrair desenvolvedores!)
O mecanismo de distribuição deve ser conveniente, padrão e o menos dependente possível. Se você estivesse tentando erradicar uma doença, você não iria distribuir o medicamente de uma forma que fosse requerer uma seringa de tamanho diferenciado para administrá-lo. Da mesma forma, o software deve estar de acordo com o padrão de métodos de construção e instalação; quanto mais ele desviar dos padrões, mais potenciais usuários e desenvolvedores desistirão e irão embora confusos.
Isso parece óbviom mas muitos projetos não se importam em padronizar seus procedimentos de instalação até ser tarde demais para isso, dizendo a si mesmos que eles podem fazer isso a qualquer momento: "Vamos resolver todas essas coisas quando o código estiver mais perto de estar pronto." O que eles não percebem é que deixando de lado o trabalho chato de terminar os procedimentos de construção e instalação, eles na verdade estão fazendo com que o código demore mais para ficar pronto—por que eles desencorajam os desenvolvedores que poderiam ter contribuído para o código. Mais insidiosamente, eles não sabem que estão perdendo todos esses desenvolvedores, porque o processo é um acúmulo não eventuais: alguém visita o we site, faz o download do software, tenta contruí-lo, falha, desiste e vai embora. Quem saberá que isso aconteceu, exceto a própria pessoa? Ninguém trabalhando no projeto irá imaginar que o interesse e boa vontade de alguém tenha sido desperdiçado.
Trabalho chato com um alto retorno deve ser feito sempre antes, e diminuir significantemente as barreiras de se entrar em um projeto atravém de um bom empacotamente traz um alto retorno.
Quando você lança um pacote para download, é vital que você dê um número único de versão a ele, para que as pessoas possam comparar dois lançamentos e saber qual substitui o outro. Uma discussão detalhada de numeração de versão pode ser encontrada em “Release Numbering”, e os detalhes de padronizar os procedimentos de construção e instalação são discutidos em “Packaging”, e também no Capítulo 7, Packaging, Releasing, and Daily Development.
Efetuar o download de pacotes de fontes é ótimo para aqueles que querem apenas instalar e usar o software, mas não é suficiente para aqueles que querem depurar ou adicionar novas funcionalidades. Os snapshots de fontes gerados toda noite podem ajudar, mas eles ainda não são o suficientemente filtrados para uma comunidade florescente de desenvolvimento. A presença de um controle de versão acessado de forma anônima é um sinal—para usuários e desenvolvedores—que este projeto está se esforçando para dar as pessoas o que elas precisam para participar. Se você não pode ofecerer prontamente um controle de versão, então coloque aviso dizendo que você pretende configurar um em breve. Insfraestrutura de controle de versão é discutida em detalhes em “Controle de Versão” no Capítulo 3, Infra-estrutura técnica.
O mesmo vale para o bug tracker do projeto. A importância de um sistema de bug tracking não se aplica apenas na utilidade para desenvolvedores, mas o que ele significa para quem oberva o projeto. Para muitas pessoas, um banco de dados de bug acessível é um dos sinais mais fortes de que um projeto deva ser levado a sério. Além disso, quanto maior o número de bugs no banco de dados, melhor para a visibilidade do projeto. Isso pode parecem sem sentido, mas lembre-se que o número de bugs registrados realmente dependem de três coisas: o número absoluto de bugs presentes no software, o número de usuários do software, e a conveniência de qual esses usuários conseguem registrar novos bugs. Destes três fatores, os últimos dois são mais significantes que o primeiro. Qualquer software de tamanho e complexidade suficientes tem, essencialmente, um número arbitrário de bugs esperando para serem descobertos. A verdadeira questão é, de que melhor maneira o projeto vai guardar e prioritizar esses bugs? Um projeto com um largo e bem mantido banco de dados de bugs ( significando que os bugs são respondidos imediatamente, bugs duplicados são unificados, etc.) gera, portanto, uma melhor impressão do que um projeto com nenhum banco de dados de bugs, ou com um banco de dados quase vazio.
Claro que, se o seu projeto está apenas começando, então o banco de dados de bugs conterá muito poucos bugs, e não se tem muito o que você possa fazer sobre isso. Mas se a página de status enfatiza que o projeto se encontra em fase inicial, e se as pessoas perceberem que a maioria dos bugs que preenchem o banco de dados foram enviados recentemente, elas podem concluir disso que o projeto ainda tem uma taxa saudável de bugs conhecidos, e não serão injustamente alarmados pelo número absolutamente baixo de bugs gravados.
Note que os bug trackers são frequentemente usados não somente para rastrearem bugs, mas solicitações de melhorias, mudanças de documentação, tarefas pendentes e assim por diante. Os detalhes sobre o uso de um bug tracker estão cobertos em “Bug Tracker” no Capítulo 3, Infra-estrutura técnica, então não irei comentá-los aqui. A importância, do ponto de vista da apresentação, é justamente o de ter um bug tracker, e ter certeza de que este esteja visível na página inicial do projeto.
Os visitantes normalmente querem saber como alcançar os seres humanos envolvidos no projeto. Providencie os endereços das listas de discussões, das salas de bate-papo, dos canais de IRC, e de qualquer outros fórums onde os outros envolvidos com o software possam ser alcançados. Deixe claro que você e os outros autores do projeto estão inscritos a essas listas de discussões, assim, as pessoas veem que se tem alguma forma de enviarem seus feedbacks aos desenvolvedores. A sua presença nas listas não implica um comprometimento em responder a todas as perguntas ou em implementar todos os pedidos de novos recursos. A longo prazo, a maioria dos usuários provavelmente nunca se juntará aos fórums de qualquer maneira, mas eles estarão confortáveis em saber que poderiam se alguma vez necessitassem.
Nos primeiros "passos" de um projeto, não há necessidade de se ter fórums de usuários e desenvolvedores separados. É muito melhor ter todos os envolvidos com o software conversando juntos, em uma única "sala". Entre os primeiros seguidores, a distinção entre desenvolvedores e usuários é frequentemente nula; para a dimensão que a distinção pode ser feita, a taxa de desenvolvedores por usuários é normalmente muito alta nos primeiros dias do projeto do que mais tarde. Enquanto você não pode presumir que cada um dos primeiros seguidores do projeto é um programador que queira reprogramar o software, você pode presumir que eles estão, pelo menos, interessados em seguirem as discussões de desenvolvimento e em adquirirem um senso da direção do projeto.
Como este capítulo é somente sobre como iniciar um projeto, é apenas o suficiente dizer que esses fórums de comunicações necessitam existir. Mais tarde, em “Handling Growth” no Capítulo 6, Communications, nós iremos examinar onde e como configurar tais fórums, quando chegar a hora, sem criar um abismo intransponível.
Se alguém estiver pensando bem em contribuir ao projeto, este deverá procurar pelo guia dos desenvolvedores. Os guias dos desenvolvedores não são tanto técnicos como sociais: eles explicam sobre como os desenvolvedores interagem uns com os outros e com os usuários, e, ultimamente, como as coisas são feitas.
Esse tópico é coberto em detalhes em “Writing It All Down” no Capítulo 4, Social and Political Infrastructure, mas os elementos básicos de um guia dos desenvolvedores são:
indicadores a fórums para a interação com outros desenvolvedores
instruções sobre como reportar bugs e submeter correções (patches)
alguma indicação de como o desenvolvimento é normalmente feito—é o projeto uma ditadura benevolente, uma democracia, ou alguma outra coisa?
A propósito, nenhum senso pejorativo é pretendido por "ditadura". É perfeitamente certo conduzir uma tirania onde um desenvolvedor particular tem poder de proibição sobre todas as mudanças. Muitos projetos triunfantes funcionam dessa maneira. Uma tirania fingindo ser uma democracia fará as pessoas se desligarem; uma tirania que diz ser uma tirania faz bem tão longo quanto o tirano for competente e confiante.
Veja http://subversion.apache.org/docs/community-guide/ para um exemplo de guia do desenvolvedor particularmente minucioso, ou http://www.openoffice.org/dev_docs/guidelines.html para um exemplo de guia mais amplo que realça sobre a administração e o espírito de participação e menos sobre questões técnicas
A questão separada de como providenciar uma instrução do software ao programador é discutida em “Documentação do desenvolvedor” mais tarde neste capítulo.
Documentação é essencial. É necessário ser algo para as pessoas lerem, mesmo que seja precário e imcompleto. Isto encaixa-se perfeitamente na categoria de "trabalho chato" referida anteriormente, e é frequentemente a primeira área onde novos projetos de código aberto falham. Fazer uma declaração de missão e uma lista de funcionalidades, escolher uma licença, sumarizar o status de desenvolvimento—essas são tarefas relativamente pequenas, das quais podem ser realizadas por completo e geralmente não é necessário retornar a elas uma vez completadas. Documentação, por outro lado, nunca está realmente finalizada, o que pode ser uma razão pela qual as pessoas demoram a iniciar.
O que é mais insidioso é que a utilidade da documentação para aqueles que a estão escrevendo é a reversa para aqueles que irão le-la. A documentação mais importante para usuários iniciais é a básica: quão rápido é configurar o software, uma visão geral de como ele funciona, talvez alguns guias para realização de tarefas comuns. Ainda que isso seja exatamente o que os escritores da documentação saibam muito bem—tão bem que pode ser difícil para que eles vejam as coisas do ponto de vista do leitos, e trabalhosamente soletrar os passos que (para os escritores) parecem tão óbvios que não valem a pena mencionar.
Não há mágica para a solução deste problema. Alguém precisa apenas sentar e escrever sobre isso, e então deixar que novos usuários o utilizem para testar sua qualidade. Use um formato simples e fácil de editar, como o HTML, texto puro, Texinfo, ou alguma outra variante do XML—algo que seja conveniente para melhorias rápidas e leves no impulso do momento. Isto não serve apenas para remover qualquer trabalho excessivo que possa impedir os escritores originais de fazer melhorias incrementais, mas também para aqueles que se unirem ao projeto mais tarde e que querem trabalhar na documentação.
Uma maneira de assugurar que a documentação inicial fique pronta é limitar seu escopo antecipadamente. Desta forma, escrevendo isso ao menos não irá parecer uma tarefa em aberto. Uma regra de outro é que ela deve atender aos seguintes critérios mínimos:
Dizer ao leitor claramente o quanto de experiência técnica é esperado que ele tenha.
Descrever clara e completamente como configurar o software, e em algum lugar próximo ao início da documentação, dizer ao usuário como executar algum tipo de teste de diagnóstico ou um comando simples para confirmar que ele configurou tudo corretamente. A documentação inicial é algumas vezes mais importante que a real documentação de uso. Quanto maior o esforço que uma pessoa empreenda na instalação e primeiros passos do software, mais persistente ela estará em imaginar uma funcionalidade avançada que não está muito bem documentada. Quando as pessoas abandonam, eles fazer isso cedo; portanto, são os estágios iniciais, como instalação, que precisam de mais suporte.
Dê um exemplo estilo tutorial de como realizar uma tarefa comum. Obviamente, muitos exemplos para muitas tarefas seria ainda melhor, mas se o tempo é limitado, pegue uma tarefa e mostre-a completamente. Uma vez que alguém entender que o software pode ser usado para uma coisa, eles irão começar a explorar sozinhos o que mais ele pode fazer—e, se você tiver sorte, passar a completar eles mesmos a documentação. O que nos leva ao próximo ponto...
Marque as áreas onde a documentação está incompleta. Mostrando aos leitores que você está a par das deficiências, você pode se alinhar com o ponto de vista deles. Sua empatia reafirma que eles não vão enfrentar uma luta para se convencer o projeto sobre o que é importante. Essas marcações não precisam representar promessas para que sejam cumpridas em nenhuma data em particular—é igualmente legítimo tratá-las como requisições em aberto de ajuda voluntária.
O último ponto é o mais importante na verdade, e pode ser aplicado em todo o projeto, não apenas na documentação. Uma contabilidade apurada de deficiências conhecidas é uma norma no mundo de código aberto. Você não precisa exagerar nas deficiências do projeto, apenas identificá-las escrupulos e desapaixonadamente quando for adequado o contexto (se na documentação, no base de bug tracking, ou em uma lista de discussão). Ninguém irá tratar isto com uma defesa por parte do projeto, nem como um compromentimento para resolver os problemas em uma data específica, a menos que o projeto faça explicitamente tal comprometimento. Desde que qualquer um que utilize o software irá descobrir suas deficiências sozinhos, é muito melhor que eles estejam preparados pscicologicamente—então o projeto irá mostrar que tem um sólido conhecimento de como ele está caminhando.
A documentação deve estar disponível de dois lugares: online (diretamente do web site), e junto com a distribuição do software (veja “Packaging” no Capítulo 7, Packaging, Releasing, and Daily Development). Ela precisa ser online, de maneira navegável, porque as pessoas geralmente leem a documentação antes de baixar o software pela primeira vez, como uma forma de auxílio para decidir ou não realizar o download. Mas ela deve também acompanhar o software, partindo do princípio de que fazer o download deve ser possuir (ser localmente acessível) tudo que alguém precisa para utilizar o pacote.
Para a documentação online, certifique-se que há um link que mostre toda a documentação em uma única página HTML (coloque uma nota como "monolítico" ou "tudo em um" ou "grande página única" próximo do link, para que as pessoas saibam que pode levar um tempo para carregar). Isto é útil por que as pessoas geralmente querem procurar por uma palavra ou frase específica por toda a documentação. Geralmente, eles já sabem o que estão procurando; só não se lembram em que seção estava. Para tais pessoas, nada é mais frustante do que encontrar uma página HTML para o índice analítico, e outra página diferente para a introdução, e uma outra página diferente para instruções de instalação, etc. Quando as páginas estão quebradas desta forma, a função de busca dos browsers é inútil. O estilo de páginas separadas é útil para aqueles que já sabem qual seção precisam, ou quem quer ler toda a documentação do início ao fim em sequência. Mas esta não é a forma mais comum em que a documentação é acessada. Muito mais frequentemente, alguém que está basicamente familiarizado com o software está retornando para procutar por uma palavra ou frase específica. Ao falhar em fornecer um único e pesquisável documento, só fará a vida deles mais difícil.
A documentação do desenvolvedor é escrita para ajugar os programadores a entenderem o código, para que eles possam corrigi-lo e extende-lo. Isso é um pouco diferente do guia dos desenvolvedores discutido previamente, que é mais social do que técnico. O guia dos desenvolvedores diz aos programadores como interagir uns com os outros; a documentação do desenvolvedor diz a eles como interagir com o código em si. Os dois são geralmente empacotados juntos em um documento para conveniência (assim como o exemplo http://subversion.apache.org/docs/community-guide/ dado anteriormente), mas eles não precisam ser necessariamente assim.
Embora a documentação do desenvolvedor possa ser muito útil, não há razão para atrasar um lançamento para fazê-la. Enquanto os autores originais estão disponíveis (e dispostos) a responder questões sobre o código, isso será suficiente para começar. Na verdade, tendo que responder as mesmas questões diversas vezes é uma motivação comum para escrever a documentação. Mas mesmo antes dela ser escrita, contribuintes determinados ainda consiguirão achar o caminho pelo código. A força que move as pessoas a usar o tempo aprendendo a base do código é que o código faz algo útil para elas. Se as pessoas colocarem fé nisso, irão dedicar seu tempo para entende-lo; se elas não colocarem fé, nenhuma quantidade de documentação de desenvolvedor irá fazer ou mante-las no projeto..
Se você tem tempo para escrever a documentação para apenas um público, faça isso para os usuários. Toda a documentação é também, com efeito, uma documentação de desenvolvedor; qualquer programador que irá trabalhar com uma parte do software vai precisar se familiarizar em como usá-lo. Mais tarde, quando você notar programadores perguntado a mesma coisa várias vezes, separe um tempo para escrever alguns documentos separados para eles.
Alguns projetos usam wikis para sua documentação inicial, ou mesmo como sua documentação primária. Pela minha experiência, isto apenas funciona se o wiki é frequentemente editado por poucas pessoas que concordam em como a documentação deve ser organizada e que tipo de "voz" ela deve ter. Veja “Wikis” no Capítulo 3, Infra-estrutura técnica para maiores detalhes.
Se o projeto possui uma interface gráfica de usuários, ou se gera gráficos ou caso contrário uma saída distintiva, disponibilize alguns exemplos no web site do projeto, pode ser a captura das telas ou apenas arquivos. Ambos atendem a necessidade das pessoas de gratificação instantânea: uma simples captura de tela pode ser mais convincente que parágrafos de textos descritivos e conversas de listas de e-mail, pois uma captura de tela é uma prova que não precisa de argumentos de que o software funciona. Ele pode ter bugs, pode ser difícil de instalar, pode ter sua documentação incompleta, mas a captura de tela ainda é uma prova que se alguém se esforçou o suficiente, podemos colocá-lo em execução.
Existem muitas outras coisas que você pode colocar no web site do projeto, se você tiver tempo, ou se por uma razão ou outra elas sejam especialmente apropriada: uma página de novidades, uma página com histórico do projeto, uma página com links relacionados, uma funcionalidade de busca no site, um link para doações, etc. Nenhuma delas são necessárias no início, mas as tenha em mente para o futuro.
Existem alguns sites que proveem hospedagem grátis e infraestrutura para projetos de código aberto: uma área web, controle de versões, bug tracker, uma área de download, fóruns de discussão, backups regulares, etc. Os detalhes variam de site para site, mas os mesmos serviços básicos são oferecidos em todos eles. Ao usar um desses sites, você tem bastante de graça; o que fica de lado obviamente é o controle total e detalhado do usuário. O serviço de hospedagem decide qual o software que o site executa, e pode controlar, ou ao menos influenciar na aparência das páginas da web do projeto.
Veja “Canned Hosting” no Capítulo 3, Infra-estrutura técnica para uma discussão mais detalhada das vantagens e desvantagens de hospedagem enlatada, e uma lista de sites que a oferecem.
[11] Nota do tradutor: Livro original cita Sun Microsystems. Originalmente, o projeto era patrocinado pela Sun Microsystems, que foi comprada e incorporada a empresa Oracle