Como documentar o projeto com uma wiki bem organizada

E, de quebra, umas dicas de markdown

Aparecido Ferreira
Dec 15, 2019 · 5 min read

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!

Concrete

Nós desenvolvemos produtos digitais com inovação, agilidade…

Aparecido Ferreira

Written by

Analista Quality Assurance (QA). Concrete (Part of Accenture) Formado em Engenharia da Computação

Concrete

Concrete

Nós desenvolvemos produtos digitais com inovação, agilidade e excelentes práticas, para que o mercado brasileiro e latino-americano acompanhe a velocidade do mercado digital mundial.

More From Medium

More on Artigos from Concrete

More on Artigos from Concrete

Era uma vez… uma Daily!

Apr 2 · 7 min read

20

More on Artigos from Concrete

More on Artigos from Concrete

Prodcast #6 — Entretenimento

Apr 1 · 1 min read

17

More on Artigos from Concrete

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade