Solicitações para documentação técnica

A documentação técnica é um gênero textual distinto, com convenções específicas: precisão acima do estilo, estrutura acima da narrativa e completude acima da concisão. As instruções que funcionam para publicações de blog ou e-mails produzem o registro inadequado para a documentação técnica.

As instruções eficazes para documentação técnica incorporam explicitamente o gênero — o tipo de documento, o nível de conhecimento presumido do leitor, a estrutura padrão desse tipo de documento e a convenção de voz (normalmente segunda pessoa em guias práticos e terceira pessoa em documentos de referência).

Um README é a porta de entrada de um projeto. Sua estrutura padrão é bem estabelecida. Uma instrução eficaz para README especifica cada seção:

• Nome do projeto e descrição em uma linha
• O que ele faz: 2 ou 3 frases sobre sua finalidade
• Pré-requisitos: o que precisa estar instalado
• Instalação: etapas numeradas com comandos
• Início rápido: exemplo mínimo funcional
• Configuração: variáveis de ambiente e opções
• Contribuição: como enviar solicitações de alteração
• Licença

Fornecer todos os nomes das seções na instrução produz um README completo. As seções ausentes serão omitidas sem uma instrução explícita.

Um gerador estruturado de README que aceita metadados do projeto:

A documentação de API tem uma estrutura rígida. Cada entrada de ponto de acesso precisa de: método HTTP, caminho, descrição, parâmetros, corpo da requisição, formato da resposta, códigos de erro e um exemplo. As instruções devem especificar todos esses elementos:

"Escreva a documentação de API para um ponto de acesso REST. Inclua: método (POST), caminho (/api/v1/users), descrição, tabela de parâmetros (nome, tipo, obrigatório, descrição), exemplo de corpo da requisição em JSON, exemplo de resposta de sucesso (200) em JSON e respostas de erro (400, 401, 422) com exemplos em JSON. Voz: terceira pessoa, presente do indicativo. Use tabelas em Markdown para os parâmetros."

Cada elemento estrutural deve ser nomeado explicitamente — o modelo não adivinhará seu padrão de documentação.

Os guias passo a passo são procedimentais: levam o leitor do estado A (problema) ao estado B (solução) por meio de etapas numeradas. Elementos do prompt para guias passo a passo:

• Pré-requisitos: o que deve ser verdadeiro antes de começar
• Resultado: o que o leitor terá alcançado
• Etapas: numeradas, cada uma com uma ação — não várias ações em uma única etapa
• Exemplos de código: um por etapa, quando relevante, com a linguagem especificada
• Validação: como o leitor sabe que cada etapa foi concluída com sucesso
• Solução de problemas: modos comuns de falha nas duas ou três etapas mais complexas

A documentação técnica tem um requisito de precisão maior que a maioria dos tipos de conteúdo. Duas técnicas para melhorar a precisão em prompts de documentação:

Forneça o código real: cole as assinaturas reais das funções, as opções de configuração ou a especificação da API. O modelo documenta o que de fato existe, em vez de inventar detalhes.

Solicite uma etapa de verificação: "Depois de escrever cada etapa, observe qualquer suposição que estiver fazendo sobre o ambiente do usuário ou o comportamento do sistema. Sinalize tudo o que eu deveria verificar antes de publicar."

Nunca use documentação gerada por IA sem revisão técnica — o modelo documentará com confiança coisas que não existem ou estão incorretas.

Os exemplos de código são o elemento mais importante da documentação técnica. Inclua instruções explícitas no prompt:

• "Inclua um exemplo de código funcional para cada conceito principal. Os exemplos devem ser autocontidos — o leitor deve conseguir copiá-los, colá-los e executá-los."
• "Mostre tanto o uso correto quanto um erro comum, com um comentário explicando por que o erro falha."
• "Os exemplos de código devem usar nomes de variáveis e dados realistas, não 'foo', 'bar', 'teste'."
• "Linguagem: Python 3.11. Use anotações de tipo. Inclua tratamento de erros para a chamada de rede."

Sem instruções explícitas sobre os exemplos de código, o modelo pode produzir trechos incompletos de pseudocódigo que não funcionam de fato.

A documentação técnica tem uma voz específica, diferente da de outros tipos de texto:

• Imperativo na segunda pessoa para procedimentos: "Clique em Configurações. Selecione a aba API. Insira sua chave."
• Terceira pessoa para documentos de referência: "O método authenticate() retorna um token Bearer válido por 24 horas."
• Presente do indicativo: "A função retorna...", não "A função retornará..."
• Sem ressalvas: "Execute este comando", não "Talvez seja conveniente considerar a execução deste comando"
• Terminologia consistente: use o mesmo termo para o mesmo conceito em todo o texto — não use sinônimos

Os registros de alterações e as notas de versão têm um formato convencional que os prompts devem definir:

"Escreva as notas de versão da versão 2.3.0. Formato: cabeçalho da versão, data de lançamento e, depois, três seções: 'Adicionado' (novos recursos), 'Alterado' (modificações em recursos existentes), 'Corrigido' (correções de erros). Cada item: uma linha, voz ativa, começando com um verbo. Público: desenvolvedores que integram esta biblioteca. Tom: preciso e neutro — sem linguagem de marketing. Estas são as alterações: [liste as alterações reais]."

Fornecer as alterações reais como dados de entrada garante a precisão. Sem elas, o modelo inventará notas de versão plausíveis, mas fictícias.

Depois de gerar a documentação técnica, execute um prompt de verificação de completude:

A documentação técnica frequentemente precisa atender tanto a leitores técnicos quanto a leitores não técnicos. Um padrão prático de prompt:

"Escreva esta documentação em duas camadas. Primeira camada: um resumo não técnico em 3 frases (o que faz, por que é importante, quando usá-lo). Segunda camada: a especificação técnica completa. Use um separador visual claro entre as camadas. Isso permite que gestores não técnicos leiam o resumo e parem; leitores técnicos podem ignorar o resumo e ler a especificação."

A documentação em duas camadas é mais útil do que tentar escrever uma única versão que atenda inadequadamente aos dois públicos.

A documentação técnica é um gênero específico que exige precisão, estrutura e uma voz no imperativo da segunda pessoa para procedimentos. Prompts eficazes especificam o tipo de documento, as seções obrigatórias pelo nome, os requisitos dos exemplos de código (autocontidos, com nomes realistas de variáveis e versão da linguagem) e a convenção de voz da documentação.

A técnica de precisão mais importante: sempre forneça o código real, a especificação da API ou os dados de configuração como entrada — nunca peça ao modelo que invente detalhes técnicos. Sempre inclua uma revisão técnica humana antes de publicar documentação gerada por IA.

Na lição final, você aplicará técnicas de elaboração de prompts a conteúdos criativos e de narrativa.