Escribir con IA
Estrategias prácticas para escribir documentación de Jamdesk con herramientas de IA. Cubre prompts efectivos, listas de revisión y errores comunes.
Estas estrategias funcionan sin importar qué herramienta de IA uses: Claude Code, Cursor, Codex, Copilot o cualquier otra. Para la configuración específica de cada herramienta, consulta Claude Code, Cursor o Codex.
Por qué MDX funciona bien con IA
MDX es uno de los formatos más fáciles de usar para las herramientas de IA:
- Sintaxis conocida: los modelos de IA se entrenan con millones de archivos Markdown, por lo que generan MDX válido con muy poca instrucción.
- Componentes estructurados:
<Card>,<Steps>y<Tabs>tienen patrones predecibles que los modelos aprenden rápido. - Texto plano: MDX no tiene formatos binarios, esquemas propietarios ni artefactos de build que una herramienta de IA deba interpretar.
Escribe mejores prompts
La diferencia entre una documentación generada por IA mediocre y una buena suele estar en el prompt. Sé específico sobre lo que quieres.
Write docs for the webhook feature.Document authentication.Create a getting started guide.Esto produce resultados genéricos e inflados porque la IA no tiene restricciones.
Patrones de prompts que funcionan
| Patrón | Ejemplo |
|---|---|
| Especifica el lector | "El lector es un desarrollador backend que nunca ha usado nuestra API" |
| Nombra la estructura | "Usa Steps para el flujo de configuración y luego Tabs para las variantes de idioma" |
| Establece límites de longitud | "Mantén la introducción en menos de 2 oraciones" o "Cada respuesta del acordeón debe tener entre 3 y 4 líneas" |
| Señala el código fuente | "Haz referencia a la implementación en /src/auth para mayor precisión" |
| Indica qué omitir | "No expliques qué es REST. Omite la teoría." |
| Da una página de ejemplo | "Sigue el tono y la estructura de /quickstart" |
Revisa el resultado de la IA
Las herramientas de IA producen MDX estructuralmente correcto la mayoría de las veces. Los problemas más sutiles son el tono, la precisión y el exceso de contenido. Repasa esta lista de verificación antes de confirmar los cambios.
Revisión de la voz
Lee el resultado en voz alta. Si suena como un chatbot, reescríbelo. Presta atención a:
- Frases de relleno: "Es importante tener en cuenta que", "Esto te permite", "Con el fin de"
- Frases evasivas: "Podrías considerar", "Generalmente se recomienda"
- Transiciones vacías: "Ahora que hemos cubierto X, pasemos a Y"
- Palabras de moda: "sin problemas", "robusto", "aprovechar", "optimizar"
Elimínalas. La página quedará más corta y mejor.
Revisión de la precisión
Las herramientas de IA producen información incorrecta con total seguridad. Verifica lo siguiente:
- ¿Los ejemplos de código realmente funcionan? Cópialos y ejecútalos.
- ¿Las opciones de configuración son reales? Compáralas con el código fuente.
- ¿Los nombres de los componentes son correctos? Usa solo componentes que existen.
- ¿La página describe el comportamiento actual y no funciones aspiracionales?
Revisión de la estructura
- El frontmatter tiene tanto
titlecomodescription - Existe un párrafo de apertura sin ningún encabezado antes
- La página termina con tarjetas de "¿Qué sigue?" dentro de un wrapper
<Columns> - Las páginas nuevas se añaden a la navegación de
docs.json - No hay componentes inventados; solo los que aparecen en la referencia de componentes
Errores comunes de la IA
Estos aparecen con la frecuencia suficiente como para tenerlos en cuenta:
Las herramientas de IA generan <CodeBlock>, <Alert>, <Section>, <Callout> y otros componentes que no existen en Jamdesk. Cíñete a los componentes que aparecen en el resumen.
Crear una página sin añadirla a docs.json es el error más común. La página existirá, pero no aparecerá en la barra lateral. Actualiza siempre la navegación al crear páginas.
A las herramientas de IA les encanta envolver cada dos párrafos en un <Note> o <Warning>. Con uno o dos callouts por página es más que suficiente. Si todo es importante, nada lo es.
Una página de 200 líneas generada por IA suele tener solo 100 líneas de contenido real. Busca explicaciones repetidas, contexto innecesario y párrafos que dicen lo mismo con otras palabras. Recorta sin piedad.
"Esta potente función te permite..." no le dice nada al lector. Reemplázalo con lo que realmente hace: "Envía solicitudes HTTP POST a tu endpoint cuando se disparan los eventos."
Mantén la documentación sincronizada
Escribir documentación es la parte fácil. Mantenerla actualizada cuando el código cambia es más difícil.
Después de lanzar una función, dale este prompt a tu herramienta 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
Usa esto como prompt inicial cuando le pidas a la IA que cree una página nueva:
Crea una página de documentación de Jamdesk
La tarjeta interactiva de arriba copia las instrucciones completas y el esqueleto. Su código fuente usa la misma sintaxis de componentes que puedes añadir a tus propias 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>