Na Locaweb começamos a usar o Gitbook para algumas documentações há certo tempo. Não participei da decisão do uso dessa ferramenta, mas posso listar alguns pontos positivos dela:
- Poder escrever os textos em markdown (que são convertidos automaticamente para html na publicação)
- A busca por palavras é muito rápida! (neste link criei uma documentação de exemplo, basta procurar por “answer” para ver a velocidade)
- Existem vários plugins disponíveis. Por exemplo, estamos usando esses: [ “mermaid”, “toggle-chapters”, “toc”, “callouts” ]
Nesse post vou focar no uso do plugin Mermaid e não pretendo detalhar como usar o Gitbook, que pode ser visto aqui. Outra opção é usar a versão “na nuvem”. Para isso basta criar uma conta no gitbook.com.
Na área de desenvolvimento de software frequentemente precisamos desenhar diagramas para documentar algo. Isso pode ajudar muito o entendimento dos sistemas, com uso de diagramas de sequência ou de estado, por exemplo.
Já usei diversas ferramentas para desenhar diagramas, mas vejo o mesmo problema para todas elas. Quando precisamos editar alguma coisa é necessário abrir o arquivo original no editor para depois exportar a imagem para PNG ou Jpeg e, às vezes, já não temos mais o arquivo original ou até o programa para edição. Assim fica impossível editar!
Há pouco tempo conheci o Mermaid, uma “linguagem” para especificar diagramas. Com ele, conseguimos fazer diagramas de sequência, de fluxo, de gantt, etc.
Na Locaweb fizemos alguns diagramas de sequência para facilitar o entendimento das integrações entre sistemas. No site do Mermaid, a especificação para esse tipo de diagrama se encontra neste link.
É possível editar em modo “live” no próprio site do Mermaid – por aqui.
Outro jeito de se testar é usando o hackmd.io. Basta criar um documento markdown e colocar o código do diagrama dentro do bloco Mermaid, como o exemplo abaixo:
```mermaid graph LR; Feature-->B[Possui pai?]; B-- não -->C[Product]; B-- sim -->D["O pai é processado?"]; ```
Esse código gera o seguinte diagrama:
Voltando ao Gitbook, para usar o Mermaid, basta adicionar o plugin Mermaid na lista de plugins no arquivo book.json, como a seguir:
{
"plugins" : [ "mermaid" ]
}
Mais detalhes sobre esse plugin podem ser vistos na em sua página.
Diferentemente do hackmd, o código do diagrama deve ficar dentro do bloco {% mermaid %} como abaixo:
{% mermaid %}
graph LR;
Feature-->B[Possui pai?];
B-- não -->C[Product];
B-- sim -->D["O pai é processado?"];
{% endmermaid %}
Espero que com essas dicas, você possa começar a criar mais diagramas para documentar suas aplicações. Qualquer dúvida, comenta aí!
