Código aberto e documentação

February 10th, 2003 § 4 comments

Shelley Powers tocou recentemente em um problema extremamente comum em projetos de código aberto: a falta de documentação, seja esta em relação à instalação ou uso do programa. Como ela mesma disse, há uma certa concepção de que não deve-se sobrecarregar os programadores responsáveis por esse tipo de projetos com demandas por documentação porque que eles já estão fazendo um favor em criar o programa.

Eu não quero criticar ou denegrir a imagem de programadores que se dispõem a criar código aberto. Pelo contrário, a generosidade de muitos desses programadores é espantosa e digna de louvor. Entretanto, a falta de documentação é realmente um problema com a maioria desses projetos, causado normalmente pela falta de recursos. Além disso, documentar um programa é uma atividade que vai necessariamente consumir tempo. E a percepção é que esse tempo poderia ser gasto em atividades mais proveitosas, como a evolução da aplicação. Em outro aspecto, a criação da documentação é também algo extremamente tedioso quando comparado à própria programação.

O resultado final é que, embora muitos dos programadores envolvidos em projetos livres sejam escritores técnicos tão bons quanto são programadores, a carência na área de documentação só aumenta. Normalmente, só projetos de grande porte, como Apache e JBoss, possuem equipes específicas que, apesar de participarem também no desenvolvimento, são primariamente responsáveis pela mesma.

Eu acredito que essa mentalidade deve ser corrigida. A comunidade que existe em volta do ideal do código aberto deve reconhecer o problema e procurar tratá-lo de maneira adequada. Cada programador deveria procurar meios de facilitar a vida de seus usuários dessa maneira — seja este usuário outro programador ou uma pessoa qualquer utilizando o programa. O foco aqui são as aplicações criadas com um público maior em mentes, não as ferramentas criadas para facilitar a vida do seu programador original.

Um ponto a se pensar é que mesmo que o usuário só recorra à documentação em último caso, ela pode ser a diferença entre um programa útil e um abandonado. Por mais nobre que seja a intenção por trás de um projeto de código aberto, sem documentação as chances de que o mesmo seja adotado são menores. A adoção corporativa é especialmente sensível neste ponto por causa de necessidades como treinamento e descoberta de soluções rápidas para eventuais problemas. A documentação tambem é necessária para que o conhecimento adquirido sobre o programa não seja perdido. Essa é inclusive a razão por trás dos how-tos do Linux. E finalmente, o atual crescimento de aplicações desktop também demanda uma qualidade maior nessa área.

Voluntários são tão necessários aqui quando em qualquer outra parte do processo de desenvolvimento. Eu acredito que alguns passos simples poderiam ter um grande resultado nessa área. Uma maneira fácil e óbvia de ajudar é escrever suas próprias experiências com a instalação ou utilização de um determinado programa ou tecnologia e doá-las ao próprio projeto. A maioria dos how-tos foram criados assim. Adicionamente, pessoas que estão interessadas em contribuir para projetos de código aberto deveriam fazê-lo também na forma de documentação. Um bom exemplo disso é o BottomFeeder, um agregador livre escrito em Smalltalk. A documentação do mesmo é criado por um voluntário. Esse é uma prática excelente e muitos projetos poderiam se beneficiar de algo semelhante. De igual forma, iniciativas com o Linux Documentation Project estão sempre precisando de mais pessoas.

Minha crença, já repetida várias vezes nessas páginas, é que tecnologia que não melhora a vida do usuário é inútil. A documentação é parte disso porque diminui as barreiras de entrada da aplicação. Além disso, essas são demandas de mercado. E nunca deve-se esquecer que projetos de código aberto, por mais livres que sejam, no que concerne a usuários, respondem a essas mesmas demandas.

§ 4 Responses to Código aberto e documentação"

  • Fora o lance de que “macho que é macho não lê manual”. Por muito tempo o Linux mesmo foi “propositalmente” user-enemy para ser um conhecimento para poucos. O famoso “de nerd para nerd”.

    Tanto que muito pedido para deixar o Linux mais amigável recebia como resposta “ah, pra que?”.

    Daí você extrapola para outros projetos de soft. livre.

  • Ronaldo says:

    Você está coberto de razão. Essa mentalidade orgulhosa ainda é um dos grandes impedimentos no sucesso do código aberto. Nunca entrou na minha cabeça a dualidade entre a filosofia de código aberto como um forma de dar mais opções para o usuário versus essa obfuscação proposital dos sistemas.

    E o que você fala ainda tem base em algumas coisas que eu li do Richard Stallman há alguns anos atrás. Não sei se ele ainda pensa isso hoje (preciso ler aquele livro sobre ele), mas na época parecia que ele considerava usuários somente seus companheiros de faculdade, trabalho e coisa assim. Nada de pensar na massa.

  • Vocês estão esquecendo que os manuais dos softwares pagos também são muito ruins, o que acaba provocando uma grande quantidade de livros e cursos ensinando a usar os produtos.

    O que precisamos, na verdade, é um projeto semelhante ao software livre: o livro livre. A questão é que escrever um livro também dá MUUUUITO trabalho, principalmente se tiver que “ficar correndo atrás” de versões e configurações. Na verdade, para mim é muito mais difícil escrever um livro (bem escrito) do que um software.

    Quanto ao livro livre, sei que já existem movimentos desse tipo. Mas precisam ser fortalecidos. Por quem, eu não sei. Mas poderiam ser criados sites do tipo SourceForge (ou o mesmo ser utilizado) para isso.

  • Ronaldo says:

    Eu sei que os manuais de produtos pagos também podem ser ruins, mas isso não justifica a falta de documentação do código aberto de forma alguma. E por piores que sejam, ainda assim a existência é melhor do que nada. Tentar usar qualquer aplicação mais complexa sem manual é um suplício.

    Sobre os livros abertos, com certeza eu acredito que eles também são parte da solução. Mas os livros dependem muito também da documentação primária do sistema, principalmente no que diz respeito a APIs.

    Como eu disse, o que precisamos é de pessoas que se disponham a escrever documentação da mesma forma que temos as que escrevem código ou coordenam projetos. Dessa forma, o gargalo que existe hoje na produção de informação sobre aplicações seria pelo menos reduzido.

What's this?

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

meta