- **Formato único (Markdown)** elimina a fragmentação. - **Git como base** garante versionamento, auditoria e colaboração. - **Docsify + GitLab** — solução leve e rápida sem geradores pesados. - **Discourse como "câmara-escura"** — ótima ideia para a consolidação coletiva de idéias antes da publicação final.
Problema: documentação em meio ao multitarefa
A agitação das tarefas cotidianas e as frequentes mudanças para “incêndios” não deixaram tempo para a documentação. O tema de otimização da escrita foi levantado entre os constantes deslocamentos entre:
- CI/CD-pipelins
- monitoramento
- automação
- R&D
- suporte aos mencionados anteriormente
- suporte aos clientes
- e rastreamento detalhado do tempo.
Nenhuma oportunidade de concentração na documentação de qualidade havia. E fazer coisas “porcarias” eu não consigo.
O que era necessário:
- logar as ações
- complementar as anotações com imagens, links e marcas temporais
- evitar misturar diferentes temas num único rascunho
- garantir que pudesse iniciar o trabalho em um computador, continuando no outro, incluindo dispositivos móveis
- manter o rastreamento dos rascunhos de forma automática para que fossem acessíveis a partir de qualquer dispositivo
- recuperar facilmente o histórico das atividades no futuro
- compartilhar rascunhos em qualquer estágio do projeto.
Na origem, a ideia era transformar o rascunho num documento completo e publicá-lo dentro da documentação de projeto sem vínculo com os períodos do cronograma. No entanto, esse enfoque permitiu ultrapassar o uso local e tornou‑se de fato parte integrante da infraestrutura de conhecimento compartilhada e passou a ser usado como padrão em projetos.
Em consequência, construi um sistema flexível, escalável e humano-orientado para documentação que considera as realidades do trabalho de engenheiro sob alta carga. O abandono dos rascunhos isolados em favor de discussões abertas — especialmente uma decisão crucial —, não só acelera o processo de tornar um documento qualificado, como também envolve a equipe no processo.
Objetivo: documentação como código
Crie os rascunhos com formatação ampliada e trabalhe com a documentação como se fosse código de programa. Isso traz vários benefícios:
- Economia de tempo no formatamento e conversão
- geração automática de documentação online
- existência de modo off‑line (graças ao cache do navegador), que é particularmente valioso:
- em redes fechadas dos clientes
- em áreas sem acesso à internet.
"Os clientes adoraram essa funcionalidade