Como documentar o projeto com uma wiki bem organizada
E, de quebra, umas dicas de markdown
Recentemente, passei por um término de projeto e me perguntaram sobre a documentação dele. Meus amigos, posso dizer que a documentação que é o terror dos Devs e dos QAs. Então, quando me fizeram a pergunta, passei um tempo pensando na melhor maneira de fazer essa documentação, e a melhor maneira que encontrei foi criar uma WIKI no repositório do projeto.
O primeiro passo foi falar com um desenvolvedor sobre como eu poderia criar um menu e, assim, dar início à WIKI. Ele criou o menu e eu fiquei com todo o trabalho de montar a documentação. Obs.: neste post vou utilizar o bitbucket como exemplo, mas tudo pode feito em qualquer repositório, ok?
Mas o que é uma Wiki?
É uma página que contém todas as informações necessárias para dar continuidade ao projeto caso algum membro saia ou comece no time. Por isso, essa página tem que conter quais as tecnologias utilizadas pelo time, quais ferramentas o time utiliza e como instalá-las e, por fim, todos os processos.
Vantagens de se ter uma Wiki
· Qualquer um pode editar;
· Se você precisar ficar ausente, a Wiki é bem fácil de manter;
· Fácil utilização e aprendizado;
· É uma documentação viva, ou seja, todos podem colaborar para deixá-la mais rica em conteúdo;
· Permite fácil navegação entre as páginas, que são ligadas por links no próprio texto (geralmente destacados em azul).
Desvantagens de se ter uma Wiki
· Se a Wiki não for feita no início, quando chegar ao fim do projeto ela pode se tornar custosa e trabalhosa;
· Deve ter uma manutenção constante, senão não serve para nada;
· Para iniciantes, a estrutura pode ser de difícil entendimento;
· Não pode conter informações que não sejam sobre o projeto.
Como criar uma Wiki, com alguns truques de Markdown
1. Entre no seu projeto e verifique se é administrador. Se a página inicial mostra o item assinalado na imagem a seguir, isso significa que é administrador.
Lembrando que se a sua página inicial não mostra o Settings, isso que dizer que você não tem permissão para criar uma WIKI. Procure alguém com acesso para criar a Wiki para você. Se o botão de Settings já aparece para você, siga para o próximo passo.
2. Ao clicar em settings vai aparecer a tela a seguir, de configuração do repositório. Procure o menu com o nome WIKI.
3. Ao clicar em WIKI a página vai solicitar se você quer deixá-la pública ou privada. O ideal é deixar privado, assim apenas os membros do time podem utilizar. Mas isso depende da sua intenção com a wiki e do projeto em que você está.
4. Agora salve e volte para o repositório, para dar início à primeira página. Para editá-la, é só clicar.
5. Agora é só clicar em wiki e vamos ser feliz colocando a mão na massa. Abaixo está a página inicial, na qual vamos colocar explicações dos principais tópicos que vamos abordar no decorrer da documentação. Clique em editar.
6. Apague tudo o que está dentro e vamos começar do zero. Por ser a página inicial, esta não pode ter o nome trocado.
Agora vamos pra parte mais legal
Escreva conforme as fotos a seguir, e a cada alteração não se esqueça de salvar. Agora veja a mágica acontecer.
1. Para criar o título em negrito uma HASHTAG = TÍTULO / duas HASHTAG = subtítulo
2. Precisa colocar um link, mas não quer que ele fique visível para não ficar feio na wiki? Basta escolher o link e o texto que você quer mostrar e digitar conforme a foto abaixo.
3. Como criar um tópico com marcador simples.
4. Como criar um subtópico com marcador simples.
5. Como destacar um trecho ou um pedaço de código importante na página da documentação.
6. Como destacar uma palavra no texto.
7. Como separar tópicos na página.
No meu caso, o cliente ficou abismado com a estrutura WIKI no momento da apresentação. Ele agradeceu e disse que essa documentação vai ajudar bastante as pessoas que entrarem no projeto, pois ficou bem completa e organizada.
E é isso! Espero que ajude, e que as wikis de vocês sejam bem estruturadas com essas dicas. Tem alguma dúvida ou algo a acrescentar? É só deixar um comentário. Até a próxima!
