Documentação com GitHub
A documentação com GitHub vai muito além de comentar exageradamente o código ou escrever manuais em arquivos Word, práticas ainda comuns na rotina de muitas pessoas desenvolvedoras. Neste artigo, vamos reforçar o que a série já mostrou: o GitHub é uma ferramenta de versionamento e também de DevOps, e a documentação prova isso.
Por que a documentação com GitHub importa
Documentação guardada fora do repositório envelhece rápido. O código muda, o arquivo Word fica esquecido em uma pasta compartilhada e ninguém sabe qual versão vale.
Por outro lado, na documentação com GitHub, o texto mora junto do código e acompanha o mesmo fluxo de trabalho. Assim, cada alteração passa por commit, histórico e revisão, como qualquer outro arquivo.
O GitHub oferece três recursos principais para isso. O README apresenta o projeto, a Wiki organiza a documentação em várias páginas e o Discussions concentra conversas sobre ideias, dúvidas e decisões.
Todos esses recursos usam Markdown, um formato de texto simples e fácil de versionar. Além disso, aceitam trechos de HTML quando precisamos de um layout mais elaborado.
O README na documentação com GitHub
A forma mais direta de apresentar um resumo do repositório é o arquivo README.md. No entanto, esse arquivo tão conhecido muitas vezes é mal produzido ou simplesmente ignorado.
O README não deve ser menosprezado, porque é a primeira impressão do seu projeto. E vale lembrar o ditado: a primeira impressão é a que fica.
Segundo a documentação oficial sobre READMEs, um bom README explica o que o projeto faz, por que ele é útil e como começar a usá-lo. Também indica onde buscar ajuda e quem mantém o projeto.
Para seguir o conceito de continuidade, usaremos o mesmo repositório dos artigos anteriores desta série, como o de gestão de projetos com GitHub.
Como não fazer um README
Por padrão, o README nasce apenas com o título do projeto. Na maioria dos repositórios, as pessoas acrescentam só um parágrafo de descrição e param por aí.
Contudo, outras pessoas desenvolvedoras, iniciantes ou não, e até recrutadores vão visitar o repositório e ler a sua documentação com GitHub. Para elas, esse arquivo pode fazer toda a diferença.
Veja um exemplo de como não deixar o README do seu projeto.
O código desse README é o seguinte.
# Article Model
Repository for versioning and project documentation used during the series of articles on GitHub.
Um bom README
Para tornar a apresentação efetiva, a documentação com GitHub precisa de mais informações no README. Primeiro, vamos centralizar o título, transformar a frase anterior em subtítulo e preparar os tópicos que pretendemos apresentar.
Para isso, usamos tags HTML com o atributo align, que o GitHub respeita na renderização.
<h1 align="center">Article Model</h1>
<p align="center"><i>Repository for versioning and project documentation used during the series of articles on GitHub.</i></p>
Logo depois, adicionamos o conteúdo dos tópicos. Lembre sempre de formatar corretamente os trechos de código, os links e as imagens.
O código completo dessa etapa fica assim.
<h1 align="center">Article Model</h1>
<p align="center"><i>Repository for versioning and project documentation used during the series of articles on GitHub.</i></p>
## About this project
This is a repository used as a base to show the operation of Issues, Discussions, Wiki and other GitHub resources in addition to code versioning.
The project inserted into this repository is a pre-existing template and is used as a basis for displaying statistical data about it.
### Technologies
<p display="inline-block">
<img width="48" src="https://www.freeiconspng.com/uploads/c-logo-icon-18.png" alt="csharp-logo"/>
<img width="48" src="https://upload.wikimedia.org/wikipedia/commons/d/d0/Blazor.png" alt="blazor-logo"/>
</p>
### Development Tools
<p display="inline-block">
<img width="48" src="https://static.wikia.nocookie.net/logopedia/images/e/ec/Microsoft_Visual_Studio_2022.svg" alt="vs-logo"/>
<img width="48" src="https://upload.wikimedia.org/wikipedia/commons/thumb/9/9a/Visual_Studio_Code_1.35_icon.svg/2048px-Visual_Studio_Code_1.35_icon.svg.png" alt="vscode-logo"/>
<img width="48" src="https://resources.jetbrains.com/storage/products/rider/img/meta/rider_logo_300x300.png" alt="rider-logo"/>
</p>
## Running
dotnet run
## References
[About issues - GitHub Docs](https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues)
[About wikis - GitHub Docs](https://docs.github.com/en/communities/documenting-your-project-with-wikis/about-wikis)
[About discussions - GitHub Docs](https://docs.github.com/en/discussions/collaborating-with-your-community-using-discussions/about-discussions)
Repare que as seções seguem uma ordem lógica. Primeiro vem o que é o projeto, depois as tecnologias, em seguida como executar e, por fim, as referências.
Badges e estatísticas do repositório
Para finalizar o README, podemos adicionar estatísticas do repositório. Por exemplo, a linguagem mais usada, o número de linguagens, a qualidade do código e muitas outras.
A nota de qualidade vem da ferramenta oferecida pela Codacy. Não vamos mostrar aqui como cadastrar o repositório na plataforma, já que o site deles traz uma documentação completa sobre isso.
Os demais badges vêm do serviço Shields.io, que gera imagens dinâmicas a partir dos dados do GitHub. Veja como fica o resultado final.
Este é o trecho de código adicionado abaixo do subtítulo.
<p align="center" display="inline-block">
<img src="https://img.shields.io/github/languages/top/Editora-Artigos/article-model" alt="top-language"/>
<img src="https://img.shields.io/github/languages/count/Editora-Artigos/article-model.svg" alt="number-of-languages"/>
<a href="https://www.codacy.com/gh/Editora-Artigos/article-model/dashboard?utm_source=github.com&utm_medium=referral&utm_content=Editora-Artigos/article-model&utm_campaign=Badge_Grade"><img src="https://app.codacy.com/project/badge/Grade/a148a172d5b6471098a0f0166b08e542"/></a>
<img alt="Repository size" src="https://img.shields.io/github/repo-size/Editora-Artigos/article-model.svg">
<a href="https://github.com/Editora-Artigos/article-model/commits/master">
<img alt="GitHub last commit" src="https://img.shields.io/github/last-commit/Editora-Artigos/article-model.svg">
</a>
<a href="https://github.com/Editora-Artigos/article-model">
<img alt="Repository issues" src="https://img.shields.io/github/issues/Editora-Artigos/article-model.svg">
</a>
<img alt="GitHub" src="https://img.shields.io/github/license/Editora-Artigos/article-model.svg">
</p>
Para trocar os badges para o seu projeto, basta substituir Editora-Artigos/article-model pelo seu usuário e pelo nome do seu repositório.
Onde o GitHub exibe o README
O GitHub reconhece o README automaticamente quando ele está na pasta .github, na raiz ou na pasta docs do repositório. Se houver mais de um, o arquivo da pasta .github tem prioridade, seguido pelo da raiz.
Além disso, o GitHub gera um sumário automático a partir dos títulos do README. Esse sumário aparece no botão de outline, no topo do arquivo renderizado.
Também existe o README de perfil. Quando você cria um repositório público com o mesmo nome do seu usuário, o README dele aparece na sua página de perfil.
Outro detalhe útil envolve os links relativos. O GitHub ajusta automaticamente links e caminhos de imagens relativos de acordo com a branch atual, por isso eles funcionam melhor que links absolutos em clones do repositório.
Por fim, cuidado com o tamanho do arquivo. Segundo a documentação, todo conteúdo acima de 500 KiB é truncado na visualização, então um README gigante perde o final.
Wiki: documentação com GitHub em várias páginas
O README é muito eficiente, mas os recursos de documentação com GitHub vão além dele. A Wiki funciona como uma ferramenta de gestão de conteúdo, com várias páginas escritas e formatadas em Markdown.
Diferente do README, que tem uma única página, a Wiki permite paginar a documentação e contar com um sumário bem posicionado. Para exemplificar a Wiki e o Discussions, vamos usar o repositório de outro projeto, já existente e de código aberto, o OldCare.
Na Wiki, todos os títulos, marcados com # ou com tags <h1> a <h6>, viram tópicos do sumário. Veja o exemplo abaixo.
# Oldcare - Caring with love
## Revision history
# 1 - Document purpose
## 1.1 - Objectives
## 1.2 - Project scope
O resultado no GitHub fica assim.
Criando uma página da wiki
Para criar a Wiki, acesse a aba Wiki no menu superior da página do repositório.
No primeiro acesso, você verá uma mensagem com os possíveis usos do recurso e um botão para criar a primeira página. Então, clique nesse botão.
Em seguida, cole o código do README que construímos acima e salve. Assim, você já consegue ver o sumário ao lado.
A partir daí, fica aberta a possibilidade de criar novas páginas e seguir documentando o repositório. Dessa forma, a documentação com GitHub cresce página a página, sem perder a organização.
A seguir, veja exemplos trazidos do repositório do OldCare.
Tabelas e acordeões na wiki
As tabelas organizam informações como o histórico de revisão de um documento. Você pode usar a sintaxe de tabela do Markdown ou, para mais controle, escrever a tabela em HTML.
O código da tabela é o seguinte.
## Revision history
<table>
<thead>
<th style="width: 25%;">Date</th>
<th style="width: 25%;">Version</th>
<th style="width: 25%;">Description</th>
<th style="width: 25%;">Participants</th>
</thead>
<tbody>
<tr>
<td>08/10/2021</td>
<td>0.1</td>
<td>Document created and first topics filled in</td>
<td>Abiratan Lopes, Brewerton Santos, Gizele Bedaque, Juan Rodrigues</td>
</tr>
<tr>
<td>08/14/2021</td>
<td>0.2</td>
<td>Vision document and meeting reports moved to GitHub; new business rules (2 to 12)</td>
<td>Abiratan Lopes, Brewerton Santos, Juan Rodrigues</td>
</tr>
</tbody>
</table>
Já os acordeões escondem conteúdo extenso até que o leitor clique no título. Para isso, usamos as tags <details> e <summary>, que o GitHub renderiza nativamente.
O código do acordeão fica assim.
# 2 - Problem description
## Problems
<details><summary>1 - Lack of control over the organization's information</summary>
<p>
<table>
<tbody>
<tr>
<th style="width: 25%;">Problem</th>
<td>Lack of control over the organization's information</td>
</tr>
<tr>
<th style="width: 25%;">Affects</th>
<td>Organization/Board/Employees</td>
</tr>
<tr>
<th style="width: 25%;">Impact</th>
<td>Difficulty meeting LGPD requirements due to the lack of segmented access control.</td>
</tr>
<tr>
<th style="width: 25%;">Solution</th>
<td>Virtualize the data and restrict access through user authentication and authorization.</td>
</tr>
</tbody>
</table>
</p>
</details>
Recursos extras da wiki
A Wiki também aceita uma barra lateral e um rodapé personalizados. Basta criar as páginas especiais _Sidebar e _Footer, que aparecem em todas as páginas.
Além disso, a Wiki é um repositório Git separado. Por isso, você pode cloná-la, editar as páginas no seu editor favorito e enviar as alterações com git push.
# substitua USER e REPOSITORY pelos valores do seu projeto
git clone https://github.com/USER/REPOSITORY.wiki.git
Vale notar que a Wiki está disponível em repositórios públicos no plano gratuito. Em repositórios privados, ela exige planos pagos, como GitHub Pro, Team ou Enterprise.
Permissões e limites da wiki
Por padrão, só quem tem acesso de escrita ao repositório consegue editar a Wiki. Em repositórios públicos, porém, você pode liberar a edição para qualquer pessoa com conta no GitHub.
Essa escolha também afeta a busca. De acordo com a documentação, os buscadores só indexam Wikis de repositórios com 500 estrelas ou mais e com a edição pública desativada.
Portanto, se a sua documentação com GitHub precisa aparecer no Google, a própria plataforma recomenda o GitHub Pages em repositórios públicos.
Existe ainda um limite prático de volume. A Wiki tem um limite flexível de 5.000 arquivos, e acima disso algumas páginas podem ficar inacessíveis.
Discussions na documentação com GitHub
O Discussions é um espaço semelhante a um fórum, com vários assuntos em pauta separados por temas e tópicos. Ele completa a documentação com GitHub, porque registra conversas, decisões e dúvidas que não cabem no README nem na Wiki.
No exemplo abaixo, vemos a página de relatórios de reunião usada no repositório do OldCare.
À esquerda, ficam as categorias, que você pode editar ou remover. No centro e à direita, aparecem os tópicos de cada registro.
Habilitando o Discussions
O uso do Discussions é livre, desde que respeite as regras de conduta do GitHub. Porém, o recurso não vem habilitado por padrão nos repositórios.
Para ativá-lo, acesse as configurações do repositório pelo menu Settings.
Em seguida, na seção Features, marque a opção Discussions.
Outra opção é acessar diretamente a URL abaixo.
https://github.com/user/repository/settings#discussions-feature
Troque user pelo nome de usuário do proprietário e repository pelo nome do repositório. Ao acessar, você verá a opção de habilitar o Discussions.
Categorias do Discussions
Ao habilitar o recurso, o GitHub cria algumas categorias padrão, como Announcements, General, Ideas, Polls, Q&A e Show and tell. Você pode renomear, excluir ou criar categorias conforme a necessidade do projeto.
A categoria Q&A merece destaque. Nela, quem abriu a pergunta pode marcar uma resposta como a solução, o que facilita a vida de quem chegar depois com a mesma dúvida.
Também é possível converter uma issue em discussão. Assim, conversas abertas demais para uma tarefa ganham um espaço próprio, sem poluir o backlog.
Discussions ou issues
Uma dúvida comum é quando usar cada recurso. Em resumo, a issue representa um trabalho a fazer, enquanto a discussão serve para conversas abertas sobre a direção e o futuro do projeto.
Além disso, o Discussions traz ferramentas próprias de moderação. Os administradores podem fixar discussões para dar mais visibilidade, bloquear conversas encerradas ou acaloradas e fechar tópicos que perderam a utilidade.
Também dá para medir a opinião da comunidade com enquetes e organizar as discussões com as mesmas labels do repositório. Com isso, a documentação com GitHub ganha um registro das decisões, e não apenas do resultado final.
Vale lembrar que o recurso também existe no nível da organização. Nesse caso, as conversas cobrem assuntos que envolvem vários repositórios ao mesmo tempo.
Boas práticas de documentação com GitHub
Primeiro, mantenha o README curto e objetivo. Ele deve responder rápido o que é o projeto e como executá-lo, enquanto os detalhes vão para a Wiki.
Depois, atualize a documentação no mesmo pull request que altera o comportamento do código. Dessa forma, documentação e código nunca ficam desalinhados.
Também use links relativos entre arquivos do repositório. Assim, os links continuam funcionando em forks e em outras branches.
Para projetos que precisam de um site de documentação, vale conhecer o GitHub Pages. No artigo sobre hospedagem gratuita com GitHub, mostramos como publicar páginas direto do repositório.
Por fim, trate a documentação como parte do produto. Um projeto bem documentado atrai colaboradores, reduz dúvidas repetidas e passa mais confiança para quem avalia o seu trabalho.
Conclusão sobre documentação com GitHub
Neste artigo, vimos que a documentação com GitHub combina três recursos complementares. O README apresenta o projeto, a Wiki organiza o conteúdo em páginas e o Discussions guarda as conversas.
Com Markdown, um pouco de HTML e alguns badges, você transforma um repositório comum em um projeto fácil de entender. Para continuar a série, leia sobre deploy de ASP.NET com GitHub Actions e Microsoft Azure e sobre GitHub Packages e GitHub Actions.
Se você está começando, o curso gratuito Fundamentos do Git e Azure DevOps é um ótimo ponto de partida. Também confira a documentação do GitHub para se aprofundar em cada recurso.
FAQ
Qual a diferença entre README e Wiki?
O README é uma única página que apresenta o projeto. A Wiki reúne várias páginas, com sumário, para documentação mais extensa.
A Wiki do GitHub é gratuita?
Sim, em repositórios públicos ela está disponível no plano gratuito. Em repositórios privados, a Wiki exige um plano pago.
Posso usar HTML no README?
Sim, o GitHub aceita parte do HTML dentro do Markdown, como alinhamento, tabelas e acordeões. Por segurança, ele remove tags e atributos considerados perigosos.
Como habilito o Discussions no meu repositório?
Acesse Settings, procure a seção Features e marque a opção Discussions. O recurso fica disponível na aba Discussions do repositório.
Onde devo colocar o README?
Coloque o README na raiz do repositório, que é o local mais comum. O GitHub também reconhece o arquivo nas pastas .github e docs.