Scrivere con l'AI
Strategie pratiche per scrivere la documentazione Jamdesk con strumenti di AI: prompt efficaci, checklist di revisione e problemi comuni.
Queste strategie funzionano indipendentemente dallo strumento di AI utilizzato: Claude Code, Cursor, Codex, Copilot o qualsiasi altro. Per la configurazione specifica degli strumenti, consulta Claude Code, Cursor o Codex.
Perché MDX funziona bene con l'AI
MDX è uno dei formati più semplici da utilizzare con gli strumenti di AI:
- Sintassi familiare: i modelli di AI sono addestrati su milioni di file Markdown, quindi producono MDX valido con un prompting minimo.
- Componenti strutturati:
<Card>,<Steps>e<Tabs>seguono schemi prevedibili che i modelli apprendono rapidamente. - Testo semplice: MDX non include formati binari, schemi proprietari o artefatti di build che uno strumento di AI debba interpretare.
Scrivere prompt migliori
La differenza tra una documentazione AI mediocre e una buona documentazione è solitamente il prompt. Specifica chiaramente ciò che vuoi ottenere.
Write docs for the webhook feature.Document authentication.Create a getting started guide.Questi prompt producono output generico e prolisso perché 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" or "Each accordion answer should be 3-4 lines" |
| Indica il 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 /quickstart" |
Revisionare l'output dell'AI
Gli strumenti di AI producono MDX strutturalmente corretto nella maggior parte dei casi. I problemi più sottili riguardano tono, accuratezza e prolissità. Esamina questa checklist prima di eseguire il commit.
Controllo dello stile
Leggi l'output ad alta voce. Se sembra scritto da un chatbot, riscrivilo. Presta attenzione a:
- Frasi riempitive: "It's important to note that", "This allows you to", "In order to"
- Formulazioni esitanti: "You might want to consider", "It's generally recommended"
- Transizioni vuote: "Now that we've covered X, let's move on to Y"
- Termini alla moda: "seamlessly", "robust", "leverage", "streamline"
Eliminali. La pagina sarà più breve e migliore.
Controllo dell'accuratezza
Gli strumenti di AI producono informazioni errate con grande sicurezza. Verifica quanto segue:
- Gli esempi di codice funzionano davvero? Copiali, incollali ed eseguili.
- Le opzioni di configurazione esistono davvero? Verificale nel codice sorgente.
- I nomi dei componenti sono corretti? Usa solo componenti esistenti.
- La pagina descrive il comportamento attuale, non funzionalità auspicabili?
Controllo della struttura
- Il frontmatter contiene sia
titlesiadescription - Esiste un paragrafo introduttivo senza un'intestazione precedente
- La pagina termina con schede "Cosa fare dopo?" in un wrapper
<Columns> - Le nuove pagine sono aggiunte alla navigazione di
docs.json - Non ci sono componenti inventati; usa solo quelli nel riferimento dei componenti
Errori comuni dell'AI
Questi errori ricorrono abbastanza spesso da richiedere attenzione:
Gli strumenti di AI generano <CodeBlock>, <Alert>, <Section>, <Callout> e altri componenti che non esistono in Jamdesk. Attieniti ai componenti elencati nella panoramica.
Creare una pagina senza aggiungerla a docs.json è l'errore più comune. La pagina esisterà, ma non apparirà nella barra laterale. Aggiorna sempre la navigazione quando crei una pagina.
Gli strumenti di AI amano racchiudere ogni altro paragrafo in un <Note> o un <Warning>. Uno o due callout per pagina sono sufficienti. Se tutto è importante, niente lo è.
Una pagina di 200 righe generata dall'AI di solito contiene 100 righe di contenuto effettivo. Cerca spiegazioni ripetute, informazioni di contesto non necessarie e paragrafi che esprimono lo stesso concetto con parole diverse. Taglia senza esitazione.
"This powerful feature allows you to..." non comunica nulla al lettore. Sostituiscila con ciò che la funzionalità fa davvero: "Send HTTP POST requests to your endpoint when events fire."
Mantenere aggiornata la documentazione
Scrivere la documentazione è la parte più semplice. Mantenerla aggiornata quando cambia il codice è più difficile.
Dopo aver rilasciato una funzionalità, invia questo prompt allo strumento di AI:
I just added [feature]. Update the docs to reflect this change.
Reference the implementation in /src/[file] for accuracy.Struttura di una pagina
Usa questo prompt come punto di partenza quando chiedi all'AI di creare una nuova pagina:
Crea una pagina di documentazione Jamdesk
La scheda interattiva precedente copia le istruzioni e la struttura complete. Il relativo codice sorgente usa la stessa sintassi dei componenti che puoi aggiungere alle tue pagine:
<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>