Comece pelo problema, não pelo Git
Docs-as-Code costuma ser apresentado como Markdown, Git, pull requests, CI e gerador estático. A equipe acaba debatendo ferramentas antes de perguntar qual problema de documentação precisa resolver: páginas desatualizadas, revisão lenta, terminologia inconsistente, links quebrados ou publicação dependente de uma pessoa.
A abordagem só vale a pena se reduzir essa fricção de forma observável.
O que Docs-as-Code realmente inclui
| Etapa | O que acontece | Simples | Mais maduro |
|---|---|---|---|
| Fonte | conteúdo é alterado | Markdown/AsciiDoc no Git | conteúdo estruturado + schema de metadata |
| Edição | autor trabalha | editor web do GitHub | github.dev, VS Code, IDE ou authoring UI |
| Preview | página futura | build local/web | preview por mudança |
| Checks | máquina encontra rotina | links + build | estilo, termos, API, acessibilidade, locales |
| Revisão | significado é validado | um reviewer | SME + revisão editorial |
| Publicação | site é atualizado | manual | CI/CD após checks |
Use o nível mínimo suficiente em cada etapa; não a versão mais complexa por padrão.
Formato de texto não exige IDE
GitHub permite editar arquivos diretamente no navegador. github.dev acrescenta busca, syntax highlighting e source control sem clone local. Um SME ocasional pode corrigir uma informação sem aprender terminal e rebase.
| Participante | Geralmente basta | Não exigir sem motivo |
|---|---|---|
| Technical writer | github.dev, VS Code ou editor preferido |
IDE específica |
| SME ocasional | editor web + preview | terminal, rebase, build local |
| Desenvolvedor | IDE + Git | CMS separada se Markdown é mais simples |
| Editor | navegador/authoring UI | detalhes internos do pipeline |
Formato canônico e interface de edição são decisões diferentes.
Um fluxo ponta a ponta razoável
Mudança de produto → rascunho → preview → checks automáticos → revisão técnica → revisão editorial → merge → publicação → verificação em produção.
Em equipe pequena uma pessoa pode acumular papéis. Pull request não precisa virar ritual. Em equipes maiores, o SME confirma fatos e o technical writer responde por tarefa do usuário, estrutura, terminologia e clareza.
Quais verificações automatizar
| Check | Detecta | Erro útil |
|---|---|---|
| Build | sintaxe, includes, templates | arquivo + causa |
| Links internos | páginas/anchors removidos | origem + destino |
| Metadata | title, owner, locale, revision | campo inválido |
| Estrutura | headings incorretos | heading afetado |
| Terminologia | termos obsoletos | termo + substituição |
| Style lint | regras editoriais | explicação curta |
| Exemplos de código | sintaxe/formato | exemplo + erro |
| Contrato API | divergência do schema/OpenAPI | campo/endpoint |
| Imagens | asset, alt, tamanho | arquivo + problema |
| Locales | idioma/revision ausente | artigo + locale |
| Segredos | token/chave | tipo sem expor segredo no log |
Warning que ninguém corrige precisa ser melhorado ou removido.
Quanto tempo isso pode economizar
Não existe um percentual universal honesto. Use hipóteses visíveis: 40 mudanças por mês × 20 minutos de checagem manual = 13 h 20 min de rotina ativa. Depois da automação, 2 minutos por mudança para interpretar resultados dão cerca de 1 h 20 min.
Hipótese: 40 × 20 minutos versus 40 × 2 minutos. Modelo de planejamento, não benchmark do setor.
Estudos industriais de code review mostram que automatizar trabalho repetitivo pode gerar impacto mensurável, mas não devemos transplantar percentuais diretamente para documentação.
Meça o próprio efeito em vez de inventar um estudo
TechWriters não deve alegar uma pesquisa em vários projetos antes de realizá-la. Durante quatro semanas, registre tempo ativo do autor, espera de review, tempo de SME/editor, defeitos pós-publicação, tempo até produção e falsos positivos. Automatize depois um grupo, como links, metadata e build, e repita.
Isso gera um caso real com contexto e limites.
Pessoas e máquinas devem revisar coisas diferentes
| Máquina | Pessoa |
|---|---|
| link existe | destino ajuda o usuário |
| heading existe | estrutura segue a tarefa |
| termo é permitido | termo é compreensível |
| exemplo bate com schema | exemplo ensina uma tarefa real |
| página compila | página ajuda a concluir o trabalho |
LLM pode sinalizar contradições, mas fatos precisam ser confirmados pelo produto, especificação, teste ou especialista responsável.
Onde começa o fanatismo
Começa quando pureza de processo importa mais que as pessoas. Se um SME corrige um parâmetro em dois minutos no navegador, não exija Node.js, clone local e rebase. Mantenha entradas simples: edição web, issue, assisted authoring ou alguém que leve a mudança até o Git.
Implante Docs-as-Code em etapas
- Semana 1: fontes no Git e histórico claro.
- Semana 2: preview e build automático.
- Semana 3: três a cinco checks úteis.
- Semana 4: separar revisão técnica e editorial onde fizer sentido.
- Após um mês: medir lead time, rotina, erros e warning noise.
Docs-as-Code funciona quando mudar, revisar e publicar fica mais fácil.
