Premissas difíceis
A ideia de otimizar a escrita de documentos surgiu no meio da agitação de tarefas. As frequentes trocas entre pipelines, monitoramento, automação, RnD, suporte e detalhamento de tempo não permitiam focar na documentação.
Registrar a história
Precisava registrar minhas ações, complementar textos com imagens, links e marcações de tempo, evitando sobreposições de temas no mesmo rascunho. Precisava fazer isso de forma que, depois, fosse fácil lembrar do andamento das tarefas.
Várias vezes, o registro do Putty/Bash ajudou a recuperar sequências confusas de trabalho no ambiente de produção. Não ignore essa possibilidade.
Publicação
Posteriormente, desejava transformar o rascunho em um documento final e publicá-lo como parte da documentação do projeto. No final, consegui sair bem além das expectativas.
O objetivo era criar rascunhos com formatação avançada e trabalhar com documentação como se fosse código.
Isso permitiu economizar tempo com formatação e tradução para o formato padrão de publicação.
Formato online
No final, o formato Markdown + Git permitiu gerar automaticamente documentação online. Como bônus, surgiu o modo offline, acessível via cache do navegador. Em redes fechadas do cliente, em voos e onde não há internet, esse modo foi muito útil. Os clientes também o apreciaram.
O formato Markdown é usado no GitLab, YouTrack, alguns mensageiros e é reconhecido por todas as modelos LLM.
Rascunhos compartilhados
Se seu trabalho não envolve finanças, seus rascunhos não devem ser ocultos. Ao contrário, permita que sejam editados em conjunto.
Meu desejo de tornar os rascunhos acessíveis ao público deu impulso à ideia de “documentação como código”. A equipe DevOps se livrou de arquivos de texto sem nome e do problema de encontrar “onde isso foi salvo?”. Não há mais problemas com versões diferentes do Word, arquivos com imagens desatualizadas ou semelhantes. Além disso, a partir do rascunho, já se obtém automaticamente uma versão online e um PDF elegante e formal.
Documentação hoje
- Escrita em formato Markdown (editor Typora ou similar com autosalvamento + commits no IDEA/PyCharm)
- Armazenada no GitLab (acessível a todos os funcionários por modelo de permissão, suporta edição multiusuário)
- Gerada automaticamente em versão online no container Docsify (atualização do código a cada minuto); os sites são expostos à internet via DNS
- Fácil exportação para PDF com o mesmo layout Vue.js, tanto para o site quanto para o arquivo
- Diagramas criados no formato Drawio (outline) e Mermaid (inline)
- Diagramas exportados em SVG (e ocasionalmente em PNG para plataformas incompatíveis) e incluem o código-fonte integrado
O que falta?
A maioria dos usuários não se importa com um único local onde a documentação seja armazenada e possa ser editada em modo multilíngue. Há poucos editores-contribuidores, mas muitos usuários comuns. Para eles, é importante encontrar rapidamente o documento desejado na versão atual, compartilhá-lo facilmente. Daí surgem algumas questões, como:
- Como montar automaticamente uma lista de documentação.
- Como classificar links no texto pela atualidade dos documentos (não no sentido de atualizações recentes, mas em termos de relevância substancial — pois ninguém quer um documento no topo da lista apenas por alterações estéticas).
- Permitir modo de pequenas edições direto no documento, sem necessidade de trabalhar com o código-fonte.
- Atualizar a documentação “em pacote”, quando algumas partes dela estão interligadas e são parcial ou totalmente reutilizadas.
- Gerar a documentação automaticamente, pois ela se torna rapidamente obsoleta.
- Alinhar não apenas a documentação, mas também lembrar que é necessário corrigir ou complementar a replicação relacionada do colaborador em canais públicos ou comunidades. A reputação dessas replicações é o que mais influencia a percepção de autoridade (as palavras de alguém ligado à documentação têm peso maior do que a própria documentação — é um fato consolidado).
O terceiro ponto já é encontrado em algumas plataformas, como o Discourse. E chegar a uma documentação estruturada pode ser auxiliado pela IA.