3 dicas para escrever uma documentação melhor

[ghost]

Originalmente publicado em: https://www.linkedin.com/pulse/3-dicas-para-escrever-uma-documenta%C3%A7%C3%A3o-melhor-corr%C3%AAa-de-mesquita/?published=t

Olá, mundo!

Atualmente estou alocado em um projeto em que o produto é a reforma de um sistema interno importante de uma empresa com relevância nacional e que está presente em vários países.

O sistema precisa ser reformado a partir de determinados requisitos, um dos requisitos é manter o micro-framework Slim como o gerenciador das rotas.

Para quem trabalha com NodeJS e não conhece o Slim, este micro-framework é bastante semelhante ao ExpressJS e faz parte do universo PHP.

No Slim, assim como no ExpressJS, você: declara rotas conforme os métodos HTTP, registra middlewares, renderiza os templates, etc.

A grande diferença entre o Slim e o ExpressJS é a documentação.

O Slim poderia ser apreendido em poucas horas caso a sua documentação fosse melhorada, e a partir desta experiência que estou tendo com o Slim gostaria de partilhar três dicas com a comunidade sobre como escrever uma documentação melhor (a partir da perspectiva de um Developer).

Dica 1) Dê exemplos práticos e de fácil compreensão

Não foi fornecido texto alternativo para esta imagem

Entre a documentação do Slim V4 e do Slim V3 existe uma diferença essencial: o Slim V3 a documentação demonstra logo no início, e de forma bastante transparente, como desenvolver uma aplicação utilizando o micro-framework.

A documentação do Slim V4 infelizmente não apresenta de forma clara um exemplo prático de como utilizar a ferramenta. Isto dificulta aumenta o tempo necessário para entender o funconamento da ferramenta, e inclusive me fez abrir a documentação do Slim V3 e sugerir o uso desta versão anterior.

Dica 2) Revise a documentação e teste as instruções pensando no seu público alvo

Não foi fornecido texto alternativo para esta imagem

A documentação do Slim V3, apesar de ser ótima, falha em uma coisa: os códigos precisam de adaptações para funcionar.

Para um Developer corrigir o erro de um código é algo que faz parte do cotidiano. Aliás, a nossa profissão é basicamente isto: solucionar problemas lógicos, procurando a maior agilidade possível, satisfazendo todos os requisitos de qualidade do projeto.

Porém, as melhores documentações raramente apresentam algum código que falha, e tanto a documentação do Slim V3 e a do Slim V4 apresentam frequentemente códigos que falham e precisam de ajustes.

Após observar os erros, e testar os códigos do Slim tanto no Windows quanto no Linux, e por estar acostumado com o NodeJS, percebi que uma parte considerável dos erros estava relacionado aos caminhos dos arquivos requisitados ou usados.

Por também estar acostumado com o filesystem do Linux e do Windows, a conclusão que cheguei e que me ajudou a previnir os erros foi a seguinte: quem escreveu os códigos da documentação estava utiliando Linux e não testou os códigos no Windows.

Apesar de existirem ferramentas que nós permitem isolar o código das características do sistema operacional, o propósito de uma documentação é facilitar a vida de todos, então é fundamental pensar em como cada segmento do seu público alvo entenderá as instruções e em quais ambientes eles estarão.

Obs.: alguns dos erros eram de escrita do código, aparentando que o código foi copiado e transferido, ajustado em algumas partes, e não foi testado após os ajustes.

3) Invista no conhecimento da comunidade

A comunidade é composta pelas pessoas que utilizam a sua ferramenta e respondem dúvidas daqueles que estão começando a utilizá-la.

Se não existe uma comunidade ativa e de tamanho razoável, quem responderá a estas perguntas e quem divulgará a sua ferramenta?

Inclusive, um dos grandes desafios de utilizar o Slim V4 (e mesmo o Slim V3) é justamente a existência de pouco conteúdo gerado pela comunidade. Ou seja, para encontrar a solução de um problema você precisa investir muito tempo pesquisando ou muito tempo tentando adivinhar o que pode estar gerando determinado erro.

Incentivar a comunidade e o seu crescimento é essencial.

Onde inspirar-se para fazer uma documentação melhor?

As documentações do VueJS, ReactJS, ExpressJS, e Webpack, são ótimas e podem servir de inspiração para você.

[ninetails]

Na época que eu utilizava PHP, utilizava um framework chamado Silex que era um microframework baseado no core do Symphony (tirando um monte de coisa) e lembro que a documentação era louvável.

Tou curtindo inclusive a importância sendo dada pra internacionalização das documentações. React e Vue tão bem traduzidos, 👏 for the community.