Artigos com a tag: Redação
A acessibilidade na documentação não termina com navegação e contraste. Exemplos de código, respostas JSON e tabelas de referência também precisam continuar claros e úteis sem depender apenas de cor.
Uma request tecnicamente válida não é automaticamente um bom exemplo. Use valores realistas e sequências que revelem o modelo da API e ajudem o developer a prever o próximo passo. Um exemplo derivado do schema pode estar sintaticamente correto e não ensinar nada.
Uma abordagem prática e verificável para Documentação de autenticação que reduz tickets de suporte, pensada para manter a documentação clara e sustentável. Como tratar «Documentação de autenticação que reduz tickets de suporte» com critérios práticos, verificáveis e sustentáveis para documentação técnica.
Uma lista útil não é mais uma estante de clássicos. Compare guias mantidos por Microsoft, Google, GitHub e IBM, use Diátaxis para testar a estrutura e transforme cada leitura em um exercício real de documentação.
Ler sobre documentação ajuda, mas a habilidade cresce mais rápido com exercícios repetidos de pesquisa, reestruturação, edição e verificação, sempre com feedback claro. “Melhorar technical writing” é amplo demais.
Uma abordagem prática e verificável para Diagramas como código: quando ajudam e quando não ajudam, pensada para manter a documentação clara e sustentável. Como tratar «Diagramas como código: quando ajudam e quando não ajudam» com critérios práticos, verificáveis e sustentáveis para documentação técnica.
Uma abordagem prática e verificável para Como documentar erros de API para permitir recuperação, pensada para manter a documentação clara e sustentável. Como tratar «Como documentar erros de API para permitir recuperação» com critérios práticos, verificáveis e sustentáveis para documentação técnica.
Boa documentação de API combina contrato legível por máquina, explicações humanas, exemplos executáveis e comportamento de erro explícito. Documentação REST fala com máquinas e pessoas.
Uma abordagem prática e verificável para Exercícios de edição que melhoram a escrita técnica, pensada para manter a documentação clara e sustentável. Como tratar «Exercícios de edição que melhoram a escrita técnica» com critérios práticos, verificáveis e sustentáveis para documentação técnica.
Uma abordagem prática e verificável para Markdown em escala: convenções que evitam o caos no repositório, pensada para manter a documentação clara e sustentável. Como tratar «Markdown em escala: convenções que evitam o caos no repositório» com critérios práticos, verificáveis e sustentáveis para documentação técnica.
Uma descrição OpenAPI pode gerar referência precisa, mas developers ainda precisam de conceitos, fluxos, autenticação, exemplos e recuperação de falhas que um schema sozinho não explica. OpenAPI descreve muito bem operações, parâmetros, requests, responses, status codes e schemas reutilizáveis.
Uma abordagem prática e verificável para Notas de versão em que o usuário consegue agir, pensada para manter a documentação clara e sustentável. Como tratar «Notas de versão em que o usuário consegue agir» com critérios práticos, verificáveis e sustentáveis para documentação técnica.