Escrever com IA
Estratégias práticas para escrever documentação do Jamdesk com ferramentas de IA, incluindo prompts eficazes, checklists de revisão e erros comuns.
Estas estratégias funcionam independentemente da ferramenta de IA usada: Claude Code, Cursor, Codex, Copilot ou qualquer outra. Para configurações específicas de cada ferramenta, consulte Claude Code, Cursor ou Codex.
Por que o MDX funciona bem com IA
O MDX é um dos formatos mais fáceis para as ferramentas de IA trabalharem:
- Sintaxe familiar: os modelos de IA são treinados com milhões de arquivos Markdown, portanto produzem MDX válido com o mínimo de instruções.
- Componentes estruturados:
<Card>,<Steps>e<Tabs>seguem padrões previsíveis que os modelos aprendem rapidamente. - Texto simples: o MDX não contém formatos binários, esquemas proprietários ou artefatos de build que uma ferramenta de IA precise interpretar.
Escreva prompts melhores
A diferença entre uma documentação de IA mediana e uma boa geralmente está no prompt. Seja específico sobre o que você quer.
Write docs for the webhook feature.Document authentication.Create a getting started guide.Eles produzem conteúdo genérico e prolixo porque a IA não tem restrições.
Padrões de prompting que funcionam
| Padrão | Exemplo |
|---|---|
| Especifique o leitor | "The reader is a backend developer who has never used our API" |
| Defina a estrutura | "Use Steps for the setup flow, then Tabs for language variants" |
| Defina limites de extensão | "Keep the intro under 2 sentences" ou "Each accordion answer should be 3-4 lines" |
| Aponte para o código-fonte | "Reference the implementation in /src/auth for accuracy" |
| Diga o que deve ser ignorado | "Don't explain what REST is. Skip the theory." |
| Forneça uma página de exemplo | "Match the tone and structure of /quickstart" |
Revise o conteúdo gerado pela IA
As ferramentas de IA produzem MDX estruturalmente correto na maior parte do tempo. Os problemas mais sutis estão no tom, na precisão e no excesso de conteúdo. Siga este checklist antes de fazer o commit.
Verificação do estilo
Leia o conteúdo em voz alta. Se parecer escrito por um chatbot, reescreva. Fique atento a:
- Frases de preenchimento: "It's important to note that", "This allows you to", "In order to"
- Hesitação: "You might want to consider", "It's generally recommended"
- Transições vazias: "Now that we've covered X, let's move on to Y"
- Termos da moda: "seamlessly", "robust", "leverage", "streamline"
Remova esses elementos. A página ficará mais curta e melhor.
Verificação da precisão
As ferramentas de IA produzem informações erradas com confiança. Verifique:
- Os exemplos de código funcionam de fato? Copie, cole e execute-os.
- As opções de configuração são reais? Confira no código-fonte.
- Os nomes dos componentes estão corretos? Use apenas componentes existentes.
- A página descreve o comportamento atual, não recursos aspiracionais?
Verificação da estrutura
- O frontmatter contém
titleedescription - Existe um parágrafo de abertura sem um título antes dele
- A página termina com cards de "Próximos passos?" dentro de um wrapper
<Columns> - As novas páginas são adicionadas à navegação de
docs.json - Não há componentes inventados; use apenas os que estão na referência de componentes
Erros comuns de IA
Eles aparecem com frequência suficiente para merecer atenção:
As 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 a docs.json é o erro mais comum. A página existirá, mas não aparecerá na barra lateral. Sempre atualize a navegação ao criar páginas.
As ferramentas de IA adoram envolver cada dois parágrafos em um <Note> ou <Warning>. Um ou dois callouts por página são suficientes. Se tudo é importante, nada é.
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 palavras diferentes. Corte sem hesitar.
"This powerful feature allows you to..." não informa nada ao leitor. Substitua pelo que o recurso realmente faz: "Send HTTP POST requests to your endpoint when events fire."
Mantenha a documentação sincronizada
Escrever a documentação é a parte fácil. Mantê-la atualizada quando o código muda é mais difícil.
Depois de lançar um recurso, envie este prompt à sua ferramenta de IA:
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 ponto de partida ao pedir à IA para criar uma nova página:
Criar uma página de documentação do Jamdesk
O card exibido acima copia as instruções e o esqueleto completos. A origem usa a mesma sintaxe de componentes que você pode adicionar às suas próprias páginas:
<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>