Este artigo foi publicado originalmente em 29/06/2018.

O manual que encontrei

Enquanto limpava minha gaveta e jogava fora papéis que não são mais úteis, me deparei com um manual criado por mim em 2015, quando eu já programava alguma coisa.

O manual é de uma série de rotinas de atualização de um sistema proprietário, e por esta razão, não irei publicar o conteúdo do manual... MAS, vou comentar algumas coisas que eu achei particularmente interessantes, ao olhar e reler o manual todo, depois de 3 anos.

A primeira coisa que me chamou a atenção foi o formato que eu usei (e continuo usando até hoje): tex, ou latex. Caso não esteja familiarizado com o termo, latex é muito usado para a escrita de documentos, artigos científicos, provas, etc..., e ele permite que você mude totalmente o layout de um documento alterando apenas uma linha. Mas ele não é um editor de texto como o MS Word, onde o que você digita é o que será impresso no final; O latex parece mais uma linguagem de programação que um editor de texto propriamente dito.
Você compila o arquivo, e ele gera um documento para você, em pdf por exemplo.

A capa é simples, limpa e direta: Título, autor, e data na parte superior, e o número da página centralizado no rodapé. Pessoalmente eu não sei que fonte é essa, mas ela é muito agradável aos olhos.
Já nas primeiras páginas (são 10 no total), eu vi que minha forma de escrita foi menos direta do que eu me lembrava. os dois primeiros capítulos, que ocupam meia página, são sobre a versão atual do meu programa e um pouco da idéia geral do que eu tinha de visão para o manual.
A outra metade é sobre como o sistema deve funcionar como um todo, descrevendo os horários default para execução de cada rotina no crontab dos servidores.

Depois disso eu ainda criei um capítulo com cada uma das quatro rotinas que devem ser executadas,  com uma parte para cada um dos programas. Descrevi, de forma detalhada, o funcionamento de cada um deles, para que quem recebesse o manual pudesse compreender o que cada coisa deve fazer (antes de se aventurar a olhar os códigos fonte).

Dediquei um capítulo todo para a forma de instalação deste sistema em clientes, e como configurar até o final, seguido de um exemplo de como testar se tudo foi feito corretamente. Interessante como eu já tinha uma preocupação grande em demonstrar todo o processo de instalação do ponto de vista de alguém que não conhece o fonte, e que não sabe programar (talvez porque eu não sabia muito também).

Ainda fiz um capítulo para backup, dizendo onde ficam, como identificar os backup, e talvez o mais importante deste manual todo: Como restaurar os backups. (Acho que a importância dos backups merecem um post exclusivo).

No final ainda tem algumas rotinas para quem for fazer a manutenção usar como guia, quase como uma folha de cola. Alguns comandos para facilitar a vida também estão presentes.

Para finalizar o manual, os capítulos: BUGS, Notas de versão, e Árvore de diretórios ( Que contém duas páginas de esquemas de todos os diretórios usados pelos programas ).

E depois de rever isso, que conclusões podemos tirar? Muitas!

Primeiro, acho que está claro que uma documentação completa, e um manual com todas as informações necessárias é importante. Mas acho que também é muito importante lembrar que a pessoa que vai ler o manual, não é (na maioria das vezes) a mesma pessoa que o escreveu.
Por isso, julgo extremamente importante o uso de exemplos que possam ser copiados e colados pelo leitor.
Recentemente terminei o meu curso de linux e shell scripting, e uma das primeiras matérias que vimos foi como abrir o manual de um determinado programa para saber como ele funciona.
Batemos nesta tecla muitas vezes durante o curso, e sempre que havia alguma dúvida, olhávamos o manual juntos, e chegávamos numa resposta. Um dos exemplos mais claros foi ao usar o programa dialog, usávamos dois comandos de ajuda:

O comando man nos trazia uma descrição de cada opção, e era muito útil para saber as ferramentas que o dialog nos dá:

man dialog

Mas também utilizávamos o comando dialog -h que carrega cada uma das opções com seus parâmetros ao lado, onde é possível copiar e colar no script para fazer funcionar:

dialog -h


Estas duas formas se complementam. Uma delas é para conhecimento de conceitos, e a outra para fazer funcionar.
Opinião pessoal:  se você tiver que escrever apenas um dos dois, faça a versão com exemplos. Por mais que o seu programa não seja usado da forma que deveria, ele ainda pode atingir o resultado desejado pelo desenvolvedor que o esta usando. Se você fizer apenas o conceitual, corre o risco de seu programa nunca ser usado.

Sempre que eu pego um manual para ler, eu quero entender como funciona, e quero fazer funcionar um exemplo na minha tela, mesmo que seja um hello world.
Isso facilita muito para o leitor compreender a ferramenta que você desenvolveu.
Sempre se dê ao trabalho de fazer o possível para que seu manual possa ser compreendido pela pessoa mais leiga, entre todos os que possivelmente o usarão.

Nunca encontrei alguém que reclamasse que o manual explica direito demais as coisas.
Por isso, volto a insistir: Faça o melhor manual possível, mesmo que dê trabalho e custe tempo.