Escrevendo com IA
Aprenda a escrever e revisar documentação com ferramentas de IA como Claude Code, Cursor e Codex, incluindo padrões de prompts e erros comuns de MDX
Estas estratégias funcionam com qualquer ferramenta de IA, incluindo Claude Code, Cursor, Codex e Copilot. Consulte Claude Code, Cursor ou Codex para a configuração específica de cada ferramenta.
Por que o MDX funciona bem com IA
MDX é um dos formatos mais fáceis para ferramentas de IA escreverem:
- Sintaxe familiar: modelos de IA são treinados com milhões de arquivos Markdown. Eles produzem MDX válido com pouca orientação.
- Componentes estruturados:
<Card>,<Steps>e<Tabs>têm padrões previsíveis que os modelos aprendem rapidamente. - Texto puro: o MDX não tem formatos binários, esquemas proprietários nem artefatos de build que uma ferramenta de IA precise interpretar.
Escreva prompts melhores
O prompt geralmente separa uma documentação de IA medíocre de uma boa. Seja específico sobre o que você quer.
Write docs for the webhook feature.Document authentication.Create a getting started guide.Esses prompts produzem resultados genéricos e inchados. A IA não tem restrições.
Padrões de prompting que funcionam
| Padrão | Exemplo |
|---|---|
| Especifique o leitor | "O leitor é um desenvolvedor backend que nunca usou nossa API" |
| Nomeie a estrutura | "Use Steps para o fluxo de configuração, depois Tabs para variantes de linguagem" |
| Defina limites de tamanho | "Mantenha a introdução em até 2 frases" ou "Cada resposta do accordion deve ter 3-4 linhas" |
| Aponte para o código-fonte | "Consulte a implementação em /src/auth para garantir precisão" |
| Diga o que pular | "Não explique o que é REST. Pule a teoria." |
| Dê uma página de exemplo | "Siga o tom e a estrutura de /quickstart" |
Revise o conteúdo gerado pela IA
Ferramentas de IA produzem MDX estruturalmente correto na maioria das vezes. Os problemas mais sutis são tom, precisão e excesso de texto. Passe por esta checklist antes de confirmar.
Verificação do estilo
Leia a saída em voz alta. Se soar como um chatbot, reescreva. Observe:
- Frases de preenchimento: "É importante notar que", "Isso permite que você", "A fim de"
- Ressalvas: "Você pode querer considerar", "Geralmente é recomendado"
- Transições vazias: "Agora que cobrimos X, vamos para Y"
- Jargões de marketing: "perfeitamente", "robusto", "aproveitar", "otimizar"
Corte tudo isso.
Verificação da precisão
Ferramentas de IA produzem informações erradas com confiança. Verifique:
- Os exemplos de código funcionam de fato? Copie, cole e execute.
- As opções de configuração são reais? Confira no código-fonte.
- Os nomes dos componentes estão corretos? Use apenas componentes que existem.
- A página descreve o comportamento atual, não funcionalidades aspiracionais?
Verificação da estrutura
- O frontmatter tem
titleedescription - Existe um parágrafo de abertura antes de qualquer heading
- A página termina com cards "What's Next?" dentro de um wrapper
<Columns> - Novas páginas são adicionadas à navegação do
docs.json - Nenhum componente inventado; apenas os da referência de componentes
Erros comuns de IA
Ferramentas de IA geram <CodeBlock>, <Alert>, <Section>, <Callout> e outros componentes que não existem no Jamdesk. Use apenas os componentes listados na visão geral.
Criar uma página sem adicioná-la ao docs.json é o erro mais comum. A página existe, mas não aparece na barra lateral. Adicione toda nova página à navegação.
Ferramentas de IA adoram envolver cada outro parágrafo em um <Note> ou <Warning>. Um ou dois callouts por página bastam.
Uma página de 200 linhas gerada por IA geralmente tem 100 linhas de conteúdo real. Procure explicações repetidas, contexto desnecessário e parágrafos que dizem a mesma coisa com outras palavras. Corte sem piedade.
"Este recurso poderoso permite que você..." não diz nada ao leitor. Diga o que ele faz: "Envie requisições HTTP POST para seu endpoint quando eventos forem disparados."
Mantenha a documentação sincronizada
Escrever documentação é a parte fácil. Mantê-la atualizada quando o código muda é mais difícil.
Peça à sua ferramenta de IA depois de lançar um recurso:
I just added [feature]. Update the docs to reflect this change.
Reference the implementation in /src/[file] for accuracy.Esqueleto de página
Use isto como prompt inicial ao pedir à IA para criar uma nova página:
Create a Jamdesk documentation page
O card acima copia as instruções completas e o esqueleto. Adicione o mesmo componente às suas páginas com este código-fonte:
<Prompt title="Create a Jamdesk documentation page" actions={["cursor", "claude", "chatgpt"]}>
Create a Jamdesk documentation page using this structure. Replace each
placeholder with specific, accurate content for the feature I describe.
```mdx
---
title: Feature Name
description: One sentence summarizing what this page covers.
---
Opening paragraph: what problem this solves and who should read this.
## Quick Start
<Steps>
<Step title="First step">What to do.</Step>
<Step title="Second step">What to do next.</Step>
</Steps>
## How It Works
Explain the mechanics. Use code examples.
## What's Next?
<Columns cols={2}>
<Card title="Related Page" icon="arrow-right" href="/path">
Why the reader would go here next
</Card>
</Columns>
```
</Prompt>
