Heathrow fechado: Suspensão de voos deve continuar nos próximos dias, afirma gerente do aeroporto de Londres
Do site da BBC
A British Airways estimou que 85% de seus voos planejados seriam realizados no sábado, mas com atrasos em todos os voos. Às 7h GMT, a maioria das partidas havia ocorrido conforme o esperado, mas, das chegadas, nove dos primeiros 20 voos programados para aterrissar foram cancelados.
Nova atualização para Minecraft adiciona templos submarinos
There has been an error in my update
api_key = "a quick brown fox"
fetch("https://api.example.com/data", headers: { 'Authorization' => api_key })
Por favor, me ajude a corrigir isso.
Documentação como Código: Um Guia para Engenheiros Multitarefa
- Formato Unificado (Markdown) elimina fragmentação.
- Git como Base garante versionamento, auditoria e colaboração.
- Docsify + GitLab — solução leve e rápida sem geradores pesados.
- Discourse como “Sandbox” — ótima ideia para refinamento coletivo de ideias antes da publicação final.
Problema: Documentar em Condições de Multitarefa
A correria do cumprimento das tarefas diárias e as constantes mudanças de foco não deixavam tempo para a documentação. A questão da otimização de sua escrita era levantada entre as constantes alternâncias entre:
- CI/CD pipelines
- monitoramento
- automação
- R&D
- suporte ao item anterior
- suporte ao cliente
- e contabilidade detalhada do tempo
Não havia oportunidade para se concentrar na documentação de qualidade. E eu não sei fazer tarefas de qualquer maneira.
O que era necessário:
- registrar ações
- complementar as anotações com imagens, links e carimbos de data/hora
- evitar a mistura de diferentes tópicos em um único rascunho
- garantir a capacidade de começar a trabalhar em um computador e continuar em outro, incluindo dispositivos móveis
- salvar os rascunhos automaticamente para que estejam disponíveis em qualquer dispositivo
- facilitar a recuperação do fluxo de trabalho no futuro
- ter a capacidade de compartilhar rascunhos em qualquer estágio do trabalho.
Inicialmente, a ideia era transformar o rascunho em um documento de trabalho completo e publicá-lo como parte da documentação do projeto sem estar vinculado aos estágios do cronograma. No final, a abordagem encontrada permitiu ir além do uso local e se tornou de fato parte da infraestrutura geral de conhecimento e frequentemente foi usada nos projetos como padrão.
No final, eu construí um sistema de documentação flexível, escalável e voltado para o ser humano que leva em consideração as realidades do trabalho de um engenheiro sob alta carga. A recusa da anonimidade e isolamento dos rascunhos é uma decisão particularmente importante. Não apenas acelera a chegada do documento à qualidade, mas também envolve a equipe no processo.
Objetivo: Documentação como Código
Crie rascunhos com formatação avançada e trabalhe com documentação assim como faz com código de software. Isso oferece várias vantagens:
- economia de tempo em formatação e conversão
- geração automática de documentação online
- modo offline (graças ao cache do navegador), o que é particularmente valioso:
- em redes fechadas do cliente
- em áreas sem internet.
“Os clientes apreciaram muito essa capacidade”, eu gostaria de escrever, mas no Brasil somos escassos em elogios a coisas úteis. Para entender que o formato pegou, basta para mim a avaliação de um cliente que usou a página armazenada em cache por um ano e tentou entender os caras do projeto que mencionavam novos diagramas e texto que o cliente não tinha visto. E quando a página foi aberta em outro computador, eles perceberam que ela não se abria para mais ninguém além deles. Portanto, o tempo gasto na documentação não foi em vão.
Pilha de Tecnologia Escolhida
A base é o formato Markdown, porque ele:
- é suportado no GitLab, YouTrack, alguns messengers
- é corretamente reconhecido por todos os LLMs modernos
- permite evitar problemas com versões do Word, imagens “fugidas” e formatos incompatíveis.
A partir do rascunho, você pode obter imediatamente:
- uma versão online
- um PDF rígido e bonito no mesmo estilo da versão online.
Prática Atual de Documentação
Hoje a documentação:
- É escrita em formato Markdown
- É armazenada no GitLab:
- acessível a todos os funcionários por modelo de função
- suporta edição multiusuário
- É coletada automaticamente na versão online:
- usa um contêiner Docsify
- a atualização ocorre a cada minuto
- sites são publicados na web via DNS (com nome de 3 ou 4 níveis para cada projeto)
- É exportada para PDF com layout unificado (baseado em Vue.js), consistente para o site e o arquivo
- Diagramas são criados em dois formatos:
- Draw.io (outline, para diagramas complexos)
- Mermaid (inline, diretamente no Markdown)
- Exportação de diagramas:
- em SVG (formato principal)
- às vezes em PNG (para plataformas incompatíveis)
- com inclusão do código fonte do diagrama dentro do arquivo.
Modelo de Três Níveis de Documentação — e sua Simplificação
Inicialmente, eu estava considerando três níveis de documentação:
- Rascunhos — pessoais, que mudam rapidamente.
- Documentação frequentemente alterada — materiais de trabalho colaborativos.
- Documentação estática — versões finais e verificadas.
No entanto, decidi:
- abandonar o anonimato e isolamento dos rascunhos,
- combinar o primeiro e o segundo níveis em Wikis gerais baseados no Discourse
- manter a documentação estática no GitLab + Docsify.
Embora não haja sincronização automática entre o segundo e o terceiro nível, acredito que essa abordagem é viável: simplifica o fluxo de conhecimento, reduz a barreira de entrada para os colegas e acelera a transição da ideia para a publicação.
Ferramentas e Formatos
| Texto | Markdown (.md) | Formato principal de escrita |
| Armazenamento | GitLab | Versionamento, revisão, acesso baseado em função |
| Publicação online | Docsify (em contêiner Docker) | Coleta automática do site a partir do Git |
| Rascunhos e discussões | Discourse | Elaboração coletiva de ideias |
| Diagramas (incorporados) | Mermaid | Blocos de diagramas, sequências diretamente no Markdown |
| Diagramas (externos) | Draw.io (.drawio → .svg) | Diagramas arquitetônicos complexos |
| Exportar para PDF | Docsify + estilo Vue unificado | Para acesso offline e entrega ao cliente |
O Que Mais
Há mais coisas a serem feitas neste esquema:
- Sincronização entre Discourse e GitLab
- Refinamento do processo de revisão e transição para um estado pronto para publicação da versão final
- Manutenção da integridade dos links
- Automação das publicações
- Mecanismo de feedback sobre discrepâncias encontradas e alertas sobre correções.