Sejamos sinceros: escrevemos pouca e má documentação. Sobretudo técnica. Porquê?
- porque não temos cultura documental: escrevemos pouco… e lemos menos;
- porque não aprendemos a fazê-lo nas escolas;
- porque o mercado é demasiado pequeno para haver technical writers;
- e porque… usamos o Word?
Sim, o Word! O Word porque é universal e porque não é apropriado para escrever documentação técnica. Logo, se universalmente usamos algo inapropriado para uma finalidade, destruímo-la. QED :-)
Universalidade
Ainda estou para conhecer alguém, profissionalmente, que nunca me tenha enviado um .doc ou .docx. Toda a gente usa o Word! Seja para escrever 3 ou 4 linhas de anotações, seja para fazer o CV, seja para escrever regulamentação. Faz-se tudo com o Word. E nem se espera que os destinatários não abram os documentos ou não os consigam editar. É assumido que sim.
Isto “secou” as alternativas, que até existem, mas têm pouca comunidade. Não me serve de muito escrever em markdown (texto) se mais ninguém o fizer.
Inapropriado para documentação técnica
Primeiro algumas premissas que considero pertinentes na produção documental:
A documentação técnica deve residir ao lado do código, num sistema de controlo de versões (SCV). Para poder evoluir com o código. É a única forma prática de o conseguir.
Uma parte substancial da documentação deve ser gerada automaticamente, como APIs, tabelas, diagramas ou modelos de dados.
Ferramentas simples e universais devem poder ser usadas para manter documentação: controlar versões, obter diferenças, corrigir ortografia, substituições massivas, etc.
Devem poder ser gerados vários formatos finais para diferentes meios de publicação. Exemplos: PDF, html único, html paginado.
Os formato finais devem poder ser construídos automaticamente.
Ora nada disto se consegue em termos práticos com o Word! O Word implica ter um enorme programa lançado, que só corre em Windows, usando as suas idiossincrasias. Ficamos fechados nesse interface, com um sistema de automatização complexo e limitado em VBA. Torna-se difícil descobrir diferenças entre versões. Torna-se impossível haver edição partilhada.
A técnica mais frequente de edição em equipa é penosamente sequencial: consiste em passar um .doc de mail em mail pelos vários editores. Isto tem impactos em termos de tempo – tem que se esperar que o actual “proprietário” passe o documento – e impede a resolução imediata de conflitos. No cenário em que o editor N estraga parte das edições do editor N-1, como passa o documento em seguida ao editor N+1, o N-1 só lhe voltará a ter acesso na revisão final, o que irá dificultar bastante o seu trabalho de correcção. Na realidade já assisti a muitas edições perderem-se desta forma.
Aos pontos acima acrescento um novo:
- A tarefa de documentar deve ser tão leve e fácil como a de programar!
Abrir o Word para documentar uma API, por exemplo, é pesado e “difícil”. Um fluxo típico de trabalho consiste em saltar de janela em janela, fazendo vários copy-pastes. Copy da janela de código, paste para a janela do Word. Todos os aspectos gráficos terão de ser feitos manualmente, um a um. Exemplo: colocar todas as variáveis em itálico, ou trechos de código numa fonte fixa.
Solução: texto!
Todos os pontos anteriores conseguem-se cumprir facilmente usando texto como representação fonte da nossa documentação.
Como tal a documentação deve ser escrita directamente em texto, ou pelo menos ter uma representação textual 1, para que possa ser processada por ferramentas simples e comuns. O texto é um formato verdadeiramente universal, logo qualquer ferramenta virtualmente o suporta.
Assim:
Edição leve e fácil: basta um editor de texto. Pode ser o nosso preferido. Pode ser o mesmo que usamos para editar código. Isto significa que podemos alterar a documentação sem sequer sair do contexto de desenvolvimento.
Colocando os ficheiros de documentação num SCV a gestão de versões é imediata. Quem editou o quê? O que mudou entre duas versões? Conseguimos reverter uma edição errada, ou até melhor, reverter as porções erradas de um dada edição. Tal como já o fazemos em relação ao código.
Edição simultânea em equipa: várias pessoas têm a hipótese de trabalhar na documentação em simultâneo, deixando o SCV tratar do merge das edições.
O sistema de construção do projecto pode ser adaptado para construir a documentação, incluindo também a geração das partes automáticas.
Referências
http://www.apeth.net/matt/iosbooktoolchain.html: descreve o processo usado para escrever o livro “Programming iOS 4”;
a documentação oficial do Python usa o sphinx (reStructuredText);
o projecto de documentação Read The Docs (RTD) também usa sphinx.
Sem comentários:
Enviar um comentário