Código aberto e documentação, continuado

March 1st, 2003 Comments Off

Algumas semanas atrás, escrevi um pouco sobre código aberto e documentação em concordância com uma entrada de Shelley Powers em seu blog. Recebi alguns comentários interessantes — tanto no blog em português quanto no em inglês — mas não tinha tido tempo para responder até agora. O que se segue abaixo é uma elaboração sobre esses comentários com uma expansão das minhas idéias sobre o assunto.

Todo o meu entendimento do movimento de código aberto é centrado no fato de que eu o considero uma filosofia. Ele não é — como muitos que conversei — uma nova opção ou metodologia de desenvolvimento. E como uma filosofia, o código aberto é coerente com a minha visão de que software que não melhora a vida dos seus usuários é irrelevante, qual seja o seu uso intencionado ou executado. A documentação se encaixa nessa visão porque reduz as barreiras de entrada tanto para o uso da aplicação quanto para sua evolução. Para clarificar, estou usando o termo documentação para se referir tanto à documentação interna de uma aplicação, que descreve seus processos e interfaces, quanto à documentação de uso, voltada para o usuário final.

Infelizmente, a documentação é vista em muitos casos como sendo algo de importância secundária no desenvolvimento de projetos de código aberto. Não é preciso olhar para muito longo para ver que esse é um problema mesmo para grandes projetos no movimento. E, como qualquer questão relacionada com o mesmo, tem muitas raízes e causas adicionais.

Cristiano Dias, comentando sobre o assunto no blog em português, escreveu sobre a hubris inerente ao movimento de código aberto, um resquício da velha mentalidade de que “programadores de verdade não precisam de manuais”, que é também o núcleo de um problema similar: a falta de comentários na maioria do código publicado. E a própria natureza do código aberto, que tende a concentrar uma boa quantidade de bons progamadores, leva pessoas a verem o código fonte como a própria documentação. Obviamente, como eu disse antes, isso somente cria mais barreiras de entrada. Para usuários comuns o código é um muro intransponível, e usuários que são programadores geralmente não tem o tempo ou a disposição para estudarem o código a fundo para corrigir erros ou extendê-lo — a não ser que isso seja absolutamente necessário.

Essa predisposição para com programadores foi algo que me chamou a atenção anos atrás quando eu li sobre o início do movimento de código aberto. Isso pode ser visto mais claramente no recente Free as in Freedom, que detalha a trajetória de Richard Stallman. O livro mostra a atitude de Stallman em relação ao compartilhamento do código de maneira clara: ele considerava os programadores com os únicos beneficiários iniciais do código aberto. Essa atitude mudou lentamente com o passar do tempo, mais ainda é prevalente em muitos círculos.

Em outro comentário postado no blog em português, Geraldo Xexéo nota que a falta de documentação é um problema que atinge o código fechado também. É desnecessário dizer que concordo; entretanto, esse fato não pode ser usado com desculpa por advogados do código aberto. Como o ditado diz: dois errados não fazem um certo. Isto é especialmente verdadeiro para projetos de código aberto cujo objetivo é ser uma alternativa primária para programas comerciais. Se o ponto do código aberto é fornecer mais opções para o usuário, é óbvio que a documentação é parte fundamental desta oferta. E com respeito ao código em si, a necessidade é ainda mais óbvia, já é muito mais difícil ler código do que escrevê-lo.

Há também a questão de liderança. Howard Hansen, em um trackback para o blog em inglês, escreveu sobre o papel do gerente de programa na Microsoft com um agregador de informação para o projeto, incluindo, é claro, a documentação. Ele conta sobre a sua própria experiência na Microsof para exemplificar a importância desse personagem para os projetos, e nota a clara falta do mesmo na maioria dos projetos de código aberto. Esta é de fato uma das maiores necessidade do código aberto. Como a maioria deles começa com uma necessidade pessoal e somente depois de expande em um produto com uma audiência, o ciclo de desenvolvimento é usualmente diferente do normal. Entretanto, é aqui que o código aberto com filosofia entra. Há uma necessidade de voluntários não só para as tarefas gloriosas de programação, mas também para as tarefas entediantes como documentação e gerência. Eric Raymond, em seu A Catedral e o Bazar, escreve sobre a figura do coordenador de desenvolvimento, que corresponde mais ou menos ao gerente de programa da Microsoft. O problema é que esta figura só geralmente só é encontrada em projetos de grande porte como Apache e JBoss, e, mesmo assim, em alguns casos a sua presença não é suficiente para garantir uma documentação melhor porque tal pessoa também programa pelo projeto e está usualmente mais focada nesta área.

Um outro problema é o reconhecimento. Como Raymond também nota em A Catedral e o Bazar, o reconhecimento é um dos maiores incetivos em projetos de código aberto. Isso também cria um problema para a documentação que geralmente é considerada uma tarefa inferior. Em um comentário deixado no blog em inglês, Kevin Conder, um desenvolvedor open source, esclarece um pouco essa questão. Ele escreve:

Eu queria retribuir à comunidade de código aberto, mas, na época, só podia contribuir com 10 horas por semana. Então pensei que poderia ter um maior impacto no projeto ajudando com a documentação, dadas as minhas limitações de tempo.

Conder documentou o projeto Csound, criando um manual de 1.000+ páginas para o mesmo. O resultado foi decepcionante. Ele continua:

  1. Voluntários para a documentação não são reconhecidos. Considere um projeto de código aberto qualquer… Quem são seus programadores? Quem o documenta? A menos que os documentadores sejam os próprios programadores, aposto que você não consegue nomeá-los.
  2. Voluntários para a documentação não são respeitados. Os líderes de projeto assumem que documentadores são estúpidos demais para programar. Uma vez, um certo programador defletiu minha questão técnica e sugeriu que eu a fizesse na lista de discussão dos “usuários”. A menos que você contribua com código, você não vale nada para a maior dos líderes de projeto.
  3. Voluntários para a documentação são consideradores desnecessários. Eu tenho visto um número cada vez maior de líderes usando Wikis para a documentação técnica. Ao invés de trabalhar duro para criar a documentação para o usuários, eles simplesmente criam um Wiki e esperam que os usuários escrevam sua própria documentação.

Embora os comentários acima parecam um exagero, eu não duvido que fiquem perto da realidade da maioria dos projetos de código aberto. A programação tende a criar um mentalidade de clube em que somente pessoas com a habilidade de criar código tem algum valor. A atitude que Conder nota no ponto 2 é prevalece especialmente nesses círculos. A menos que exibam proficiência técnica direta, as pessoas não têm valor como auxiliares. Ironicamente, este própria atitude leva à saturação dos canais de suporte de um projeto — se estes existem — quando a maior parte das dúvidas poderia se facilmente resolvida pela documentação. É claro que a maioria dos usuários só recorre à documentação em último caso. Mesmo assim, a existência da mesma server para reduzir o ruído no suporte porque preserva o conhecimento existente. Ao invés de ficar repetidamente respondendo às mesmas perguntas em detalhe, as pessoas podem simplesmente se referir à página apropriada na documentação.

Se estes são os problemas, há alguma solução? Acredito que sim. A primeira, que mencionei anteriormente, é procurar aumentar a atenção das pessoas para a questão e educá-las sobre o assunto. Isso se aplica tanto a desenvolvedores, que devem ser convencidos a ajudar, como a líderes, que devem aprender a evitar os problemas que Conder cita.

Conder inclusive dá alguns conselhos que líderes de projeto fariam bem em ouvir. Ele diz:

  1. Comece um sub-projeto de documentação com sua própria lista de discussão, repositório CVS e uma área visível no Web site do projeto.
  2. Defina um formato padrão para criar a documentação. O DocBook é usado na maioria dos projetos de código aberto de grande porte. Um guia de estilo ajuda também: “Isso é um floppy disc ou um disquete”. Nunca mude os padrões sem discutir o assunto na lista da documentação primeiro.
  3. Identifique as tarefas de documentação que precisam ser feitas e mantidas. Poste ambas no Web site do projeto e na lista de discussão da documentação.
  4. Coloque uma pessoa responsável no cargo de coordenar as submissões, tarefas e voluntários. Certifique-se de que essa pessoa responsa questões por e-mail dentro das 24 horas seguintes.
  5. Recrute voluntários e delegue tarefas. Certifique-se de que os nomes estejam associados com as tarefas no Web site do projeto.
  6. Responsa as questões da equipe da documentação. Certifique-se de que a equipe seja tratada com respeito.

Esses são conselhos sensíveis para qualquer projeto, qual seja o tamanho do mesmo. Eles não só garantem que a qualidade da documentação como também a boa integração entre as equipes do projeto e a satisfação dos envolvidos. Claro, são difíceis e dependem da boa vontade dos envolvidos. Mesmo assim, se projetos de código aberto têm que sair da pequenez para tornarem-se realmente úteis, estes são passos necessários para essa evolução.

Geraldo Xéxeo também nota a necessidade de fortalecer os movimentos de livros abertos, que não são senão outra forma de documentar uma aplicação, ainda que obviamente está documentação esteja mais voltada ao uso final do produto.

Um outro pensamento interessante sobre a documentação é que a mesma pode ser uma fonte de recursos para o projeto. No caso do JBoss, por exemplo, a documentação é oferecida como um recurso pago no site visando custear o desenvolvimento. Em grandes projetos essa pode ser uma saída para a documentação.

Por fim, como usuários também podemos fazer algo nesse sentido seja oferecendo reconhecimento ou revisando a documentação. Projetos de código aberto precisam de um tipo de nutrição diferente e todas essas coisas contam para melhoria dos mesmos.

Pelo que escrevi até agora, é fácil ver que eu sou um proponente do código aberto. E a documentação é uma área que quero investir para ajudar em quais projetos que eu vier a participar futuramente. Se cada advogado do código aberto doar um pouco que seja nessa área, o resultado pode ser fantástico.

Bem, essa é a minha resposta aos comentários que obtive. Sinta-se à vontade para adicionar os seus próprios, criticar, destruir os meus argumentos, ou fazer qualquer outra coisa que ajude no diálogo.

Comments are closed.

What's this?

You are currently reading Código aberto e documentação, continuado at Superfície Reflexiva.

meta