Jamdesk Documentation logo

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ãoExemplo
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 title e description
  • 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

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> ```

Create a Jamdesk documentation page

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>
```

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>

Próximos passos?

Atualizações automatizadas

Execute /update-jamdesk para gerar documentação a partir de mudanças no código

Componentes MDX

Referência completa dos componentes disponíveis