A documentação do Linux e de código aberto é uma bagunça: aqui está a solução

Simplesmente dizer a alguém para RTFM não é uma resposta quando o manual está desatualizado, ilegível ou inexistente. Precisamos melhorar a qualidade da nossa documentação e a forma de fazer isso é simples.

Quando eu era um usuário e programador Unix inexperiente, a resposta certa para qualquer questão técnica era RTFM, que significa "Leia o Manual F… Fine". Infelizmente, isso não mudou nas gerações Linux e software de código aberto. Já é tempo de abordarmos esta questão e provocarmos mudanças positivas. Os manuais e quase toda a documentação estão muitas vezes desatualizados, às vezes quase impossíveis de ler e, às vezes, nem existem.

Não é como se não soubéssemos desse problema. Jon Corbet, editor da LWN, a melhor publicação aprofundada do Linux e supervisor da documentação do kernel Linux, tem falado sobre isso desde que trabalha no Linux. Mas ninguém faz nada a respeito.

Ou melhor, eles fazem. Eles gemem, reclamam, mas trabalham nisso? É como se os ratos gritassem para o gato; todo mundo reclama disso, mas ninguém trabalha nisso.

Isso não é justo. Algumas pessoas trabalharam duro na documentação. Simplesmente não há um número suficiente deles, e aqueles que têm trabalhado nisso estão esgotados.

Na verdade, Alejandro Colomar, que mantém o projeto de páginas de manual do Linux nos últimos quatro anos, acabou de sair. Por que? É simples, explicou Colomar: “Tenho feito isso no meu tempo livre e nenhuma empresa patrocinou esse trabalho. … Não consigo mais sustentar esse trabalho economicamente”.

Quem pode culpá-lo?

Como Corbet apontou: "Muitas vezes reclamei que, embora milhares de desenvolvedores sejam pagos para trabalhar no kernel do Linux, não há uma única pessoa cujo trabalho seja escrever documentação para o kernel".

Não é que ninguém escreva documentação. Corbet continuou: "Há muitos desenvolvedores que escrevem documentação, não me interpretem mal; alguns deles trabalham duro nisso. Mas geralmente não é para isso que seus empregadores os pagam para fazer."

Este tem sido o caso há algum tempo. Alguns anos antes, Corbet havia apontado que “Ninguém quer pagar pela documentação” e “não há ninguém cujo trabalho seja escrever documentação para o kernel”. Esta falta de recursos dedicados resulta numa documentação de má qualidade.

Isso é um problema. Isso é um problema real.

Em particular, a documentação do kernel Linux é feia. Na reunião de encanadores Linux de 2022, Corbett comentou:

Quando comecei a manter a documentação do kernel, tudo foi jogado no diretório principal de nível superior. Um mantenedor anterior descreveu-o muito bem como 'onde quer que um transeunte aleatório anterior o tenha deixado cair'. Então melhoramos, mas ainda estamos numa situação que me lembra muito o quarto da minha filha, onde as coisas acabaram de ser jogadas em qualquer lugar. Não é boa sorte se você quiser encontrar algo.

Melhorou desde então, mas ainda não é, digamos, amigável para recém-chegados.

Não ajuda em nada que a documentação do kernel consista em "milhares de documentos individuais" escritos isoladamente, em vez de um corpo coerente de documentação. Embora tenham sido feitos esforços para organizar documentos em livros para leitores específicos, a documentação geral ainda carece de uma estrutura unificada.

Steve Rostedt, engenheiro de software do Google e desenvolvedor do kernel Linux, concordaria. Na Linux Plumbersconference do ano passado, ele disse, “quando se depara com bugs, não consegue encontrar documentos que descrevam como as coisas funcionam”. Se alguém tão experiente quanto Rostedt tiver problemas, quanta sorte você acha que um programador novato terá ao tentar encontrar uma resposta para uma pergunta difícil?

Enquanto falo sobre Linux, posso garantir que as coisas não são muito melhores em outros projetos de código aberto. Muitos deles, mesmo os mais populares, têm dificuldade em manter uma documentação abrangente e actualizada devido à insuficiência de fundos e ao rápido desenvolvimento. Quero dizer, quando seus lançamentos de código estão em um pipeline de Integração Contínua/Entrega Contínua (CI/CD) que libera programas para produção a cada um ou dois dias, a documentação nunca estará completamente atualizada.

No entanto, não estamos falando de documentação atualizada. Estou falando de documentos e manuais básicos e úteis para desenvolvedores, administradores de sistema e usuários finais.

Muitos projetos do GitHub, por exemplo, têm pouco além de um arquivo README para documentação. Isso não é útil.

Outros projetos simplesmente não parecem se importar com a documentação. Veja, por exemplo, minha interface de desktop Linux favorita, Cinnamon. Muitas pessoas usam e adoram, mas não possui um site para o usuário final; tudo o que tem é sua página GitHub. Agora, os fóruns e a comunidade do Linux Mint são ótimos, mas você precisa fazer algumas pesquisas sérias para encontrar a resposta para o seu problema do dia.

Então, o que podemos fazer sobre isso? OpenSource.com tem uma boa lista de práticas recomendadas de documentação.

1. As contribuições de valor para a documentação são tão importantes quanto as contribuições de código.

2. Coloque a documentação e o código no mesmo repositório do projeto.

3. Faça da documentação um requisito para um marco de mesclagem ou lançamento.

4. Tenha um processo de contribuição consistente para código e documentação.

5. Tenha processos bem documentados para contribuir com a documentação.

Isso é ótimo. Boa sorte em fazer com que as pessoas valorizem as contribuições de documentação tanto quanto o código. A documentação sempre foi filha negligenciada da programação.

Aqui está a solução

Você quer saber o verdadeiro segredo para melhorar a documentação de projetos de código aberto?

Preparar?

Pague os escritores. É isso.

Escrever documentação – seja um manual de 500 páginas, um tutorial rápido e sujo ou um FAQ – é um trabalho árduo. Confie em mim. Eu fiz tudo isso e, francamente, embora eu ainda escreva artigos de instruções para o linux-terminal.com de vez em quando, ninguém pode me pagar o suficiente para escrever documentação séria, muito menos manuais técnicos. É simplesmente muito trabalho para pouco dinheiro.

Outras pessoas, porém, têm talento e tempo. O que eles não têm é tempo livre. Colomar, por exemplo, parece disposto a colocar o ombro na roda das páginas do manual novamente se alguém lhe pagar.

Então, se você realmente deseja ajudar o Linux ou seu projeto de código aberto favorito, pague dinheiro de verdade a programadores ou escritores com experiência em tecnologia para escreverem documentação. O mundo da tecnologia será um lugar muito melhor.