- esbuild e Redis são exemplos de codebases com documentação excelente.
- Por meio de README, changelog, documentos de arquitetura e comentários no código, até novos usuários conseguem entender a estrutura da codebase, como ela funciona e por que foi feita dessa forma.
- Servem como bons estudos de caso para desenvolvedores que querem melhorar a documentação de código e de arquitetura de software.
Por que uma boa documentação é importante
- Ao escrever software, uma boa documentação é essencial, especialmente quando outras pessoas vão olhar ou contribuir para a codebase, ou quando você mesmo precisar consultá-la novamente no futuro.
- Usuários de software frequentemente enfrentam dificuldades por causa de documentação ausente.
- Ao contribuir para uma codebase, quanto melhor a qualidade da documentação, mais rápido é possível contribuir.
- A qualidade da documentação afeta direta ou indiretamente a experiência de autores, contribuidores e usuários.
- Os benefícios de uma boa documentação são variados: economia de tempo, aumento de contribuições externas em projetos open source, registro de decisões passadas, maior acessibilidade para mais usuários, organização do pensamento e descoberta de problemas.
A documentação do esbuild
- esbuild é um bundler JavaScript criado por Evan Wallace.
- O README do esbuild é focado no usuário final da ferramenta.
- Por meio de links para as principais seções da documentação e de uma seção chamada "Por quê?", ele explica de forma breve por que escolher o esbuild em vez de outros bundlers.
- Os documentos de arquitetura do esbuild ficam no diretório
docs, nos arquivos architecture.md e development.md.
- A documentação de arquitetura explica os princípios de design e inclui, além do texto, gráficos que ajudam a explicar os conceitos.
- O changelog do esbuild é detalhado, com resumos, explicações ampliadas e exemplos de código de antes e depois das mudanças.
A documentação do Redis
- Redis é um banco de dados em memória.
- O README do Redis compartilha boas características semelhantes às do README do esbuild, mas também é voltado tanto para contribuidores quanto para usuários finais.
- A seção sobre os aspectos internos do Redis inclui a organização do código-fonte e explicações sobre os principais arquivos.
- Os comentários no código-fonte do Redis chegam a fornecer vários parágrafos de explicação para uma única linha de código.
Encerrando
- Muitos projetos open source têm documentação excelente.
- esbuild e Redis impressionam especialmente pela qualidade da documentação.
- A documentação pode trazer restrições de tempo no curto prazo, mas economiza tempo no longo prazo.
- Em projetos usados ou com contribuições de muitas pessoas, vale reconsiderar a decisão de não documentar.
Opinião do GN⁺
- Os exemplos de documentação do esbuild e do Redis reforçam, para os desenvolvedores, a importância de documentar de forma que facilite o entendimento e a manutenção da codebase.
- A documentação é um elemento central para aumentar a sustentabilidade do projeto e incentivar a participação da comunidade.
- No caso do esbuild, além de sua função como bundler JavaScript rápido, sua excelente documentação parece ter contribuído para o crescimento do projeto.
- O Redis tem impacto positivo na comunidade de desenvolvedores por causa de uma documentação que ajuda a entender com facilidade um sistema complexo de banco de dados em memória.
- Esses exemplos podem ajudar a disseminar a importância da documentação para outros projetos open source e são especialmente úteis para ajudar engenheiros de software iniciantes a entender como documentar seus próprios projetos.
2 comentários
O esbuild já tem um README.md excelente, mas o arquivo architecture.md apresentado no texto é bonito demais!
Opiniões no Hacker News
Antirez, criador do Redis, escreveu em seu blog um texto detalhando suas ideias sobre comentários no código. Ele identifica 9 tipos de comentários usados no Redis.
Artigo bem escrito, com exemplos concretos e capturas de tela mostrando como a documentação de um projeto pode ser excelente para usuários, desenvolvedores e contribuidores.
Isso mostra a preocupação dos mantenedores com a qualidade do repositório.
Faz lembrar a série "The Architecture of Open Source Applications". Há insights interessantes.
A documentação do GitLab tem reputação de ser muito boa, embora não tenha havido muita necessidade de usá-la diretamente. Fica a dúvida se a documentação de arquitetura deles também é boa.
O projeto Postgres também dá atenção detalhada à documentação, aos arquivos readme e aos comentários no código.
Fiquei profundamente impressionado com a documentação de arquitetura do projeto esbuild. Teria sido ótimo se houvesse algo assim em bases de código com as quais trabalhei no passado.
Gosto muito dos changelogs de projetos open source. São muito mais profissionais e informativos do que os de outras entidades com fins lucrativos. Crítica ao changelog do app do banco ING por tentar ser engraçado em vez de focar em informar.
"A maior carência na comunidade de software livre hoje não é software, mas a falta de boa documentação livre que possa ser incluída com o software livre."
É mencionado que o Redis não é mais open source. O Redis agora é um software "source-available", sob a Redis Source Available License v2 (RSALv2) e a Server Side Public License v1 (SSPLv1).