Trate a documentação como parte da mudança
Quando o comportamento muda, o momento mais confiável para atualizar a documentação é no mesmo pull request. Os revisores podem comparar implementação e explicação juntas, e as tags de versão mantêm a documentação alinhada ao código lançado.
- Mantenha um README focado perto do componente que ele explica.
- Exija atualizações de documentação quando o comportamento público, a configuração ou os procedimentos operacionais mudarem.
- Use verificações de links e de estilo na integração contínua.
- Atribua responsabilidade clara para runbooks e páginas de referência de alto risco.
Escolha o tipo de documento antes de escrever
Um tutorial ensina por meio de uma sequência. Um guia prático resolve uma tarefa. Material de referência descreve o comportamento exato. Uma explicação fornece contexto e compensações. Misturar os quatro em um único README longo torna cada um mais difícil de usar.
Os registros de decisão de arquitetura (ADRs) são outro padrão útil: registre o contexto, a decisão, as alternativas e as consequências enquanto o raciocínio ainda está fresco. O Markdown mantém o registro perto do código sem exigir um fluxo de publicação separado.
Torne os exemplos de código testáveis e honestos
Os leitores copiam exemplos. Inclua as importações necessárias, nomes realistas, saída esperada e o caminho de erro relevante. Se o trecho for intencionalmente incompleto, diga isso. Um exemplo pequeno e testado vale mais do que um bloco grande que apenas parece plausível.
```bash # Validate docs before opening a pull request npm run lint npm run typecheck ``` Expected result: both commands exit with status 0.
Otimize para diffs fáceis de revisar
Use uma frase por linha somente se o repositório adotar essa convenção de forma consistente; caso contrário, quebre as linhas naturalmente e deixe as ferramentas cuidarem da apresentação. Evite reformatar um arquivo inteiro durante uma edição de conteúdo. Títulos estáveis e links no estilo de referência podem tornar documentos grandes mais fáceis de alterar sem diffs ruidosos.
- Dê a títulos nomes específicos que permaneçam úteis nas âncoras geradas.
- Mantenha tabelas estreitas e evite células com muito texto.
- Use links relativos para arquivos que se movem junto com o repositório.
- Não cole segredos, logs privados ou dados de produção não editados em exemplos.
Use a conversão como ponto de partida para migração
Um arquivo do Word, uma planilha, um PDF ou uma apresentação de slides podem conter conhecimento valioso que ainda não se encaixa em um fluxo de trabalho de docs-as-code. Convertê-lo para Markdown remove boa parte da camada de apresentação, mas ainda é preciso normalizar títulos, corrigir links, definir os limites dos arquivos e confirmar a precisão técnica.
Mantenha o documento original até que a versão convertida seja revisada. Para dados calculados ou registros assinados, o original pode continuar sendo a fonte de verdade mesmo depois que um snapshot Markdown legível for adicionado ao repositório.