Scrivere con l'AI
Scopri come scrivere e rivedere la documentazione con strumenti AI come Claude Code, Cursor e Codex, inclusi schemi di prompt ed errori MDX comuni
Queste strategie funzionano con qualsiasi strumento AI, inclusi Claude Code, Cursor, Codex e Copilot. Consulta Claude Code, Cursor o Codex per la configurazione specifica di ciascuno strumento.
Perché MDX funziona bene con l'AI
MDX è uno dei formati più facili da scrivere per gli strumenti AI:
- Sintassi familiare: i modelli AI sono addestrati su milioni di file Markdown. Producono MDX valido con pochi prompt.
- Componenti strutturati:
<Card>,<Steps>e<Tabs>hanno schemi prevedibili che i modelli imparano rapidamente. - Testo semplice: MDX non ha formati binari, schemi proprietari o artefatti di build che uno strumento AI debba interpretare.
Scrivere prompt migliori
Il prompt di solito è ciò che separa una documentazione AI mediocre da una buona. Sii specifico su ciò che vuoi.
Write docs for the webhook feature.Document authentication.Create a getting started guide.Questi producono un output generico e gonfio. L'AI non ha vincoli.
Schemi di prompting efficaci
| Schema | Esempio |
|---|---|
| Specifica il lettore | "The reader is a backend developer who has never used our API" |
| Indica la struttura | "Use Steps for the setup flow, then Tabs for language variants" |
| Imposta limiti di lunghezza | "Keep the intro under 2 sentences" oppure "Each accordion answer should be 3-4 lines" |
| Rimanda al codice sorgente | "Reference the implementation in /src/auth for accuracy" |
| Indica cosa tralasciare | "Don't explain what REST is. Skip the theory." |
| Fornisci una pagina di esempio | "Match the tone and structure of /it/quickstart" |
Revisionare l'output dell'AI
Gli strumenti AI producono quasi sempre MDX strutturalmente corretto. I problemi più sottili riguardano tono, accuratezza e ridondanza. Passa in rassegna questa checklist prima di fare commit.
Controllo dello stile
Leggi l'output ad alta voce. Se suona come un chatbot, riscrivilo. Fai attenzione a:
- Frasi di riempimento: "It's important to note that", "This allows you to", "In order to"
- Cautele eccessive: "You might want to consider", "It's generally recommended"
- Transizioni vuote: "Now that we've covered X, let's move on to Y"
- Parole di moda: "seamlessly", "robust", "leverage", "streamline"
Eliminale.
Controllo dell'accuratezza
Gli strumenti AI producono con sicurezza informazioni sbagliate. Verifica:
- Gli esempi di codice funzionano davvero? Copiali e eseguili.
- Le opzioni di configurazione esistono? Controllale nel codice sorgente.
- I nomi dei componenti sono corretti? Usa solo componenti esistenti.
- La pagina descrive il comportamento attuale, non funzionalità aspirazionali?
Controllo della struttura
- Il frontmatter contiene sia
titlesiadescription - Esiste un paragrafo introduttivo senza alcun titolo prima
- La pagina termina con card "What's Next?" in un wrapper
<Columns> - Le nuove pagine sono aggiunte alla navigazione in
docs.json - Nessun componente inventato; solo quelli nel riferimento dei componenti
Errori comuni dell'AI
Gli strumenti AI generano <CodeBlock>, <Alert>, <Section>, <Callout> e altri componenti che non esistono in Jamdesk. Usa solo i componenti elencati nella panoramica.
Creare una pagina senza aggiungerla a docs.json è l'errore più comune. La pagina esiste ma non compare nella barra laterale. Aggiungi ogni nuova pagina alla navigazione.
Gli strumenti AI tendono a racchiudere ogni secondo paragrafo in un <Note> o <Warning>. Uno o due callout per pagina sono più che sufficienti.
Una pagina di 200 righe generata dall'AI di solito contiene 100 righe di contenuto effettivo. Cerca spiegazioni ripetute, background non necessario e paragrafi che dicono la stessa cosa con parole diverse. Taglia senza esitazione.
"This powerful feature allows you to..." non dice nulla al lettore. Dì cosa fa: "Send HTTP POST requests to your endpoint when events fire."
Mantenere aggiornata la documentazione
Scrivere la documentazione è la parte facile. Mantenerla aggiornata quando il codice cambia è più difficile.
Chiedi al tuo strumento AI dopo aver rilasciato una funzionalità:
I just added [feature]. Update the docs to reflect this change.
Reference the implementation in /src/[file] for accuracy.Struttura di una pagina
Usalo come prompt di partenza quando chiedi all'AI di creare una nuova pagina:
Create a Jamdesk documentation page
La card sopra copia le istruzioni complete e lo scheletro. Aggiungi lo stesso componente alle tue pagine con questo sorgente:
<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>