Guia prático para documentação de projetos git usando wikis

O que são wikis

Uma wiki, no contexto de desenvolvimento de softwares em Git, é uma seção do seu repositório para documentação mais extensa do seu projeto. Pode ser usada para compartilhar conteúdo de documentação detalhada sobre seu projeto, como a forma de usá-lo, como ele foi elaborado e quais são os seus princípios nucleares.

Diferença em relação a um README

Um arquivo de README documenta brevemente o que seu projeto pode fazer, enquanto uma wiki pode ser usada para providenciar documentação adicional. Enquanto o principal público alvo de um README são outros desenvolvedores ou contribuintes do código, wikis são voltadas para explicar o software para usuários finais.

De forma geral, o uso de READMEs em projetos de software é encorajado por desenvolvedores. No GitHub, famoso site para hospedagem de código fonte, caso a página principal do seu repositório possua um arquivo README, ele é automaticamente apresentado na página inicial.  Por outro lado, o uso de wikis não necessariamente é essencial para qualquer tipo de projeto.

Para que tipos de projeto usar wikis?

Projetos extensos, para os quais uma explicação seria muito complexa para ser feita por um único e longo arquivo README. A wiki permite implementação em diversas páginas e navegação hierárquica (como em capítulos de um livro). Essa estrutura permite o registro e atualização mais sustentáveis do conhecimento sobre o projeto, o que é desejável para equipes de projetos de médio a longo prazo.

Projetos cujos usuários finais sejam leigos em programação e desenvolvimento de software. A wiki permite explicações separadas do código fonte, permitindo que o usuário entenda como usar o programa sem ter que olhar o código ou mesmo abrir um terminal. Além disso, o formato da wiki é mais propício para documentação de tutoriais guiados, podendo conter prints e exemplos passo a passo.

Como criar e editar wikis no GitHub

Aqui, pressupõe-se que o usuário tenha permissões de edição.

Para adicionar páginas wiki, e, deste modo, hospedar a documentação para o repositório do seu projeto, siga estes passos:

1. No GitHub, acesse a página do seu repositório.
2. No menu superior, procure por "📖 Wiki" e acesse esta aba.
3. Clique em "Create new page", "New page", ou, "Create the first page" caso seja a sua primeira página wiki do repositório atual.
4. Edite o formato de escrita de sua preferência no menu "Edit mode" (por padrão, o formato é o Markdown), e não esqueça de escrever um título.
5. E, enfim, use o editor de texto para criar o conteúdo da página de documentação do seu projeto.
6. Após isso, no campo "Edit message", digite uma mensagem de confirmação descrevendo a nova página que está adicionando.
7. Para fazer o commit das alterações realizadas, clique em "Save page".

Para editar páginas wiki, repita os dois primeiros passos acima e, na sequência:

• Identifique e selecione a página que deseja editar.
• Clique em "Edit" no menu suspenso na parte superior.
• E, enfim, edite a página da forma que preferir e salve as modificações realizadas, repetindo os passos de 4 a 7 acima.

Como criar wikis no GitLab

Aqui, pressupõe-se que o usuário tenha permissões de edição. Para criar uma página inicial, uma nova página ou, mesmo, editar uma página já existente, siga as instruções padrão:

1. Na barra lateral esquerda, clique em "Search or go to" e localize seu projeto ou grupo o qual deseja documentar.
2. Selecione "Plan" > "Wiki".

A partir daqui, para criar a página inicial, :

• Selecione "Create your first page".
• Defina um título para sua página.
• Neste caso, o GitLab exige que a página inicial do seu wiki tenha path home
• Defina um formato para estilizar e formatar seu texto.
• Adicione uma mensagem para sua home page na seção "Content", vale dizer que esta mensagem poderá ser editada porteriormente.
• Adicione uma mensagem para seu commit ("Commit message"). Se não o fizer, o Git cria uma.
• Finalize clicando em "Create page".

Para criar uma nova página wiki:

• Selecione o menu de três pontos verticais (Wiki actions) e selecione a opção "New page".
• Após isso, siga os passos padrão de selecionar um formato para o seu texto, adicionar um título para sua página, adicionar conteúdo de documentação do projeto (aqui, é possível anexar um arquivo, e o GilLab o armazenará no repositório do wiki).
• Se preferir, o usuário pode alterar o caminho ("Path") da página desmarcar, isso é feito ao desmarcar "Generate page path from title" e alterar o "Path" da página.
• Adicione uma mensagem de commit.
• Por fim, selecione "Create page".

Para editar, siga:

• Identifique e selecione a página que deseja editar.
• Use o atalho de teclado 'e', e selecione "Edit".
• Faça as alterações.
• Salve em "Save changes". (Alterações não salvas são preservadas no armazenamento local para evitar perdas.)

Para excluir:

• Vá até a página que deseja excluir.
• Selecione o menu "Wiki actions" > "Delete page".
• Confirme a exclusão.

Como criar ou editar wikis localmente

Como as wikis fazem parte do repositório Git, é possível fazer alterações localmente e executar push delas no seu repositório.

No GitHub, depois de criar uma página inicial, para clonar o repositório em seu computador com a URL fornecida, faça:

$ git clone https://github.com/SEU-USERNAME/SEU-REPOSITORY.wiki.git

Após clonar o wiki, o usuário pode adicionar novos arquivos, editar os existentes e fazer commit das alterações. Vale destacar que somente as alterações enviadas por push ao branch-padrão serão ativadas e disponibilizadas. Exemplo de demonstração prática de criação de wikis no GitHub e GitLab.