Molti sviluppatori pensano che la documentazione delle API sia scritta per le persone. Non è più così.
Quando un ingegnere chiede a ChatGPT come autenticarsi a un'API, creare un webhook o gestire il rate limiting, la tua documentazione compete direttamente con altre 50 fonti nella valutazione del sistema AI. I motori AI valutano la documentazione tecnica come fonte primaria. Un riferimento API ben strutturato può essere citato centinaia di volte al mese. Uno ottimizzato male viene ignorato del tutto.
Il problema è che la documentazione tecnica non è stata pensata per l'AI. È stata pensata per persone che cercano su Google, cliccano sui link e leggono passo dopo passo. I sistemi AI leggono in un altro modo. Estraggono, dividono in blocchi, attribuiscono e citano. La struttura della documentazione, gli esempi di codice e la gestione delle versioni influenzano tutti la possibilità che un sistema AI trovi, capisca e citi i tuoi contenuti. Questo capitolo spiega come si presenta l'ottimizzazione della documentazione tecnica e quali modifiche precise rendono le tue docs da invisibili a indispensabili.
Cos'è l'ottimizzazione della documentazione tecnica per l'AI?
L'ottimizzazione della documentazione tecnica per l'AI è la pratica di strutturare riferimenti API, guide di implementazione, documentazione sugli errori ed esempi di codice in modo che i crawler AI possano leggerli, estrarli, attribuirli e citarli con precisione. A differenza della SEO tradizionale, che ottimizza per il seguire i link e per la corrispondenza delle parole chiave, l'ottimizzazione della documentazione per l'AI punta sulla chiarezza semantica, sulla facilità di estrazione e sulla densità di fatti.
Un sistema AI che indicizza le tue docs fa tre cose. Scansiona le pagine per leggerle (crawlability). Salva le sezioni dei tuoi contenuti come blocchi distinti, che possono essere recuperati quando servono (chunking). E decide se citare il tuo blocco come fonte quando genera una risposta (valore come citazione). La maggior parte della documentazione fallisce in uno o più di questi passaggi.
Perché la citazione AI conta per i contenuti tecnici
La documentazione tecnica è uno dei tipi di contenuto di cui i sistemi AI si fidano di più. Quando uno sviluppatore chiede a ChatGPT come usare la tua API, il sistema dà più peso alla documentazione tecnica che ai post del blog o alle discussioni nei forum, perché le API richiedono precisione. Un endpoint sbagliato, un parametro mancante o un metodo di autenticazione errato rompono l'integrazione.
I sistemi AI premiano questa percezione. Il riferimento API ha più probabilità di essere citato dei contenuti del tuo blog, perché è più specifico, più verificabile e più completo. Il problema è che gli sviluppatori non ti scoprono con la ricerca AI come scoprono i contenuti di un blog. Ti scoprono con ricerche dirette sulla tua API, con il passaparola e con l'adozione precoce. Una volta che trovano la tua documentazione, l'ottimizzazione che fai decide se altri sviluppatori troveranno la tua soluzione tramite l'AI.
Come i sistemi AI leggono ed estraggono dalla documentazione tecnica
I crawler AI trattano la tua documentazione come un database strutturato, non come un racconto. Ecco cosa succede quando un sistema AI indicizza le tue docs.
Prima di tutto, il crawler richiede la pagina (oppure la piattaforma di documentazione la serve tramite un'API). Se le tue docs sono costruite con framework JavaScript senza rendering lato server, il crawler riceve un HTML vuoto. È uno dei problemi più comuni. Se le tue docs usano un framework JavaScript moderno, verifica che il tuo provider di hosting o la tua piattaforma di documentazione generi le pagine lato server, altrimenti i tuoi contenuti diventano invisibili per la maggior parte dei crawler AI.
In secondo luogo, il sistema divide la pagina in blocchi. Non salva come un unico blocco l'intero riferimento API da 4.000 parole. Lo spezza in sezioni, di solito tra le 100 e le 300 parole ciascuna. Qui la gerarchia dei titoli conta moltissimo. Se salti dei livelli di titolo (passando da un H1 a un H3), il sistema si confonde su quale contenuto appartenga a cosa. Se i titoli sono vaghi ("Panoramica" invece di "Metodi di autenticazione"), il sistema non può capire di cosa parla ogni sezione senza leggere ogni parola.
In terzo luogo, il sistema assegna dei metadati a ogni blocco. Legge il titolo, il testo del paragrafo, gli esempi di codice e i dati strutturati (markup dello schema) per capire di cosa parla il blocco. Poi lo salva in un database vettoriale, dove i concetti simili si raggruppano. Quando uno sviluppatore fa una domanda, il sistema trova i gruppi vicini al vettore della domanda e recupera i blocchi più pertinenti.
In quarto luogo, il sistema decide se citare il tuo blocco. Dipende dalla densità di fatti, dalla chiarezza, dalla specificità e dal fatto che l'informazione esista anche altrove. Una spiegazione generica su come impostare gli header viene citata meno di un esempio preciso che mostra quali header richiede la tua API.
Ottimizza la struttura della documentazione per l'estrazione da parte dell'AI
La gerarchia dei titoli è il tuo strumento di ottimizzazione più potente. Usa titoli H2 e H3 coerenti e specifici, che dicano al sistema esattamente di cosa parla ogni sezione.
Usa titoli specifici e completi
Titolo ERRATO: "Autenticazione"
Titolo CORRETTO: "Come autenticare le richieste API"
La versione corretta dice al sistema che questa sezione contiene informazioni pratiche sull'autenticazione. Quella errata è ambigua. Potrebbe spiegare perché esiste l'autenticazione, come funziona o cosa fare se non riesce. Sii specifico.
Fai corrispondere la struttura dei titoli alla gerarchia dei contenuti
Se la tua API ha più metodi di autenticazione (chiave API, OAuth, JWT), usa sottotitoli H3 per ognuno, non elenchi puntati o testo in grassetto. Gli elenchi puntati vanno bene per elencare elementi. Non vanno bene per sezioni con un nome che hanno bisogno di una struttura propria.
Struttura corretta
- H2: Come autenticare le richieste API
- H3: Autenticazione con chiave API
- H3: Autenticazione con OAuth 2.0
- H3: Autenticazione con JWT
Questa struttura dice al sistema che l'autenticazione è l'argomento principale e che sotto di essa esistono tre metodi distinti. Il sistema può estrarre da sola la sezione su OAuth e citarla quando uno sviluppatore chiede proprio di OAuth.
Introduci i passaggi in modo esplicito
Se descrivi una sequenza di passaggi, introducili in modo esplicito. Non dare per scontato che il sistema capisca che i tuoi punti elenco sono passaggi.
ERRATO: "Per autenticarti, inserisci la tua chiave API nell'header della richiesta. Usa il nome di header Authorization. Scrivi il valore nel formato Bearer YOUR_API_KEY."
CORRETTO: "Per autenticare la tua richiesta API, segui questi tre passaggi. Primo, trova la tua chiave API nelle impostazioni del tuo account WEMASY. Secondo, aggiungi l'header Authorization alla richiesta. Terzo, scrivi il valore nel formato Bearer YOUR_API_KEY."
La versione corretta usa un linguaggio esplicito che dice al sistema che sono passaggi in sequenza, non fatti collegati tra loro.
Prepara i tuoi esempi di codice all'estrazione
Gli esempi di codice sono il tipo di contenuto più citato nella documentazione tecnica. I sistemi AI amano citare il codice perché non è ambiguo. Ma non tutti gli esempi di codice sono uguali. Il modo in cui presenti il codice influenza la possibilità che il sistema lo estragga e lo citi in modo corretto.
Abbina il codice a un testo che lo precede e spiega cosa fa
Non mettere i blocchi di codice da soli. Ogni esempio di codice dovrebbe essere preceduto da una frase che spiega cosa dimostra.
Struttura ERRATA
[Blocco di codice]
[Paragrafo di spiegazione]
Struttura CORRETTA
[Frase di spiegazione]
[Blocco di codice]
[Contesto aggiuntivo o gestione degli errori]
La spiegazione che precede dice al sistema cosa aspettarsi dal codice. Offre anche un contesto che il sistema può citare prima di mostrare il codice vero e proprio.
Concentra ogni esempio su un solo compito
Non mostrare un esempio di codice di 50 righe che dimostra cinque cose diverse. Dividilo in più esempi, ognuno con un comportamento preciso. Un sistema AI che estrae un esempio di codice deve essere sicuro che l'esempio sia davvero completo e non dipenda da una configurazione mostrata altrove.
Includi la gestione degli errori negli esempi di codice
Gli sviluppatori veri chiedono sempre degli errori. Se nel tuo esempio manca la gestione degli errori, gli sviluppatori chiederanno al sistema AI cosa succede quando quel codice fallisce. Se la tua documentazione non risponde, il sistema AI citerà la documentazione di qualcun altro che lo fa. Includi blocchi try-catch, risposte di errore o note esplicite sugli errori che l'operazione può restituire.
Struttura gli endpoint del riferimento API per la comprensione da parte dell'AI
Il riferimento ai tuoi endpoint API è la documentazione più importante per essere citati dall'AI. Fai in modo che ogni endpoint si capisca da solo, senza costringere chi legge a saltare da una pagina all'altra.
Apri ogni endpoint dicendo cosa fa
Non iniziare il riferimento di un endpoint con "L'endpoint Users restituisce i dati degli utenti". Inizia con una frase completa che spiega l'azione.
ERRATO: "L'endpoint /users offre l'accesso ai record degli utenti."
CORRETTO: "Recupera l'elenco di tutti gli utenti del tuo workspace."
La versione corretta è un'azione. Dice al sistema esattamente cosa fa questo endpoint, senza costringerlo a dedurlo dal percorso.
Includi la struttura completa della richiesta in ogni sezione di endpoint
Non rimandare a una sezione comune "Autenticazione" dando per scontato che il sistema unisca le informazioni. Indica come autenticarsi, quali header includere e come appare la richiesta completa nella documentazione di ogni endpoint. Così ogni endpoint si può estrarre da solo.
Mostra sia le risposte di successo sia quelle di errore
Documenta come appare una risposta riuscita. Poi documenta come appaiono le risposte di errore. Includi almeno un esempio per ogni condizione di errore comune (401 Unauthorized, 404 Not Found, 429 Rate Limited). Quando un sistema AI ha sia le risposte di successo sia quelle di errore, può dare agli sviluppatori indicazioni più complete.
Gestisci le versioni per la visibilità nell'AI
Molte API hanno più versioni. V1, V2 e a volte versioni legacy ancora in produzione. Il versionamento crea un problema preciso per i sistemi AI. Quale versione va citata quando qualcuno chiede della tua API?
La maggior parte dei sistemi AI cita la versione più recente che riesce a trovare. Se la tua versione attuale è la v3, ma la tua piattaforma di documentazione rende la v1 e la v2 altrettanto facili da trovare, il sistema potrebbe citare la versione vecchia e lasciare gli sviluppatori con istruzioni superate.
Usa una struttura degli URL che indichi la versione prioritaria
Se puoi, pubblica la documentazione attuale a un URL pulito (/docs/api) e metti le versioni più vecchie a URL con la versione (/docs/api/v1, /docs/api/v2). Questo segnala ai sistemi AI che l'URL senza versione è quello attuale e consigliato.
Aggiungi avvisi di versione alla documentazione vecchia
Se mantieni la documentazione delle versioni più vecchie (perché gli sviluppatori le usano ancora), aggiungi un chiaro avviso di versione in cima. Non dare per scontato che il sistema legga l'URL e capisca quale versione sta guardando.
Avviso BUONO: "Stai leggendo la documentazione dell'API v1. Questa versione è deprecata e sarà rimossa il 1 gennaio 2027. Ti consigliamo di passare all'API v3. Consulta la guida all'aggiornamento."
Rendi esplicita la deprecazione. Indica la data di fine supporto. Collega la versione attuale e una guida alla migrazione. Così il sistema ha tutto ciò che serve per inquadrare bene la documentazione deprecata.
Crea guide di integrazione e tutorial facili da estrarre
Le guide di integrazione sono diverse dai riferimenti API. Sono discorsive, orientate al compito e pensate per gli sviluppatori che implementano flussi specifici. I sistemi AI le citano in modo diverso.
Parti dal risultato finale, non dalla spiegazione
Una guida all'integrazione sulla creazione di un ricevitore di webhook dovrebbe aprirsi mostrando com'è fatto un ricevitore di webhook funzionante. Poi mostra i passaggi per costruirlo. Poi mostra come testarlo.
Quest'ordine conta perché i sistemi AI estraggono le sezioni in modo indipendente. Se uno sviluppatore chiede "come ascolto gli eventi dei webhook", il sistema potrebbe prendere la tua sezione sui listener dei webhook. Quella sezione dovrebbe essere abbastanza completa da reggersi da sola.
Usa passaggi numerati con punti di decisione espliciti
La logica condizionale dev'essere esplicita. Non dire "se devi filtrare gli eventi, aggiungi questo codice". Poni invece una domanda diretta come titolo.
Struttura CORRETTA
Passaggio 1: Crea un endpoint per il webhook
Passaggio 2: Registra l'URL del tuo endpoint
Passaggio 3: Gestisci i webhook in arrivo
Passaggio 4: Devi filtrare gli eventi? (Sì / No)
- Se sì: aggiungi il filtro degli eventi
- Se no: passa ai test
Passaggio 5: Testa il tuo webhook
Questa struttura rende evidente al sistema AI dove c'è la logica condizionale e quali sono le opzioni.
Marca la tua documentazione con dati strutturati
Il markup dello schema dice ai sistemi AI che tipo di contenuto stanno leggendo. Guida all'implementazione? Riferimento API? Tutorial? I dati strutturati rendono lo scopo esplicito.
Usa lo schema Article per guide e documentazione di integrazione
Qualsiasi documentazione che sia più di una semplice pagina di riferimento dovrebbe usare lo schema Article. Includi l'autore, la data di pubblicazione e la data dell'ultima modifica. Questo aiuta il sistema a capire autorevolezza e freschezza.
Usa lo schema HowTo per le guide passo dopo passo
Se la tua documentazione ha passaggi numerati, usa lo schema HowTo. Includi ogni passaggio con un nome e una descrizione. Questo aiuta il sistema a estrarre i singoli passaggi e a citare quello pertinente.
Usa lo schema FAQPage per le domande comuni
Se le tue docs hanno una sezione di domande frequenti, marcala. Non dare per scontato che il sistema la riconosca come FAQ.
Come WEMASY supporta la documentazione tecnica
Il creatore di siti di WEMASY include strumenti che semplificano la struttura della documentazione tecnica. Puoi impostare gerarchie di titoli chiare, inserire blocchi di codice con la formattazione giusta e organizzare la documentazione su più pagine in strutture coerenti. WEMASY gestisce anche in automatico il rendering lato server, quindi la tua documentazione è del tutto scansionabile dai sistemi AI. Scopri cosa è incluso in ogni piano.
Domande frequenti
La mia documentazione tecnica deve stare su un dominio separato?
No. La tua documentazione può stare su docs.yourbrand.com, su yourbrand.com/docs o anche su yourbrand.com/api. Conta che sia accessibile al pubblico, scansionabile e aggiornata con costanza. I sistemi AI citano la documentazione ovunque si trovi. Però tenerla su un dominio separato può aiutarti a seguire il traffico dall'AI separatamente da quello del sito principale. Con il creatore di siti di WEMASY puoi impostarlo direttamente sul tuo sito.
Ogni quanto devo aggiornare la documentazione della mia API?
Aggiorna la documentazione ogni volta che rilasci modifiche all'API. Aggiungi un changelog visibile ai crawler AI che mostri cosa è cambiato e quando. I sistemi AI danno più peso alla documentazione recente che a quella datata. Se hai rilasciato l'API v3 sei mesi fa, ma la documentazione della v2 si posiziona più in alto nei risultati di ricerca, hai un problema di freschezza dei contenuti. Tieni aggiornata la versione attuale.
Che differenza c'è tra documentazione per le persone e documentazione per l'AI?
La documentazione per le persone può essere discorsiva e dare il contesto per scontato. Quella per l'AI deve essere esplicita e completa in sé. Chi legge ricorderà che hai parlato di autenticazione prima, nella guida. Un sistema AI che estrae una singola sezione no. Scrivi come se ogni sezione venisse letta da sola. Includi tutto il contesto che serve per capire quella sezione senza andare altrove.
Per la citazione AI contano di più gli esempi di codice o le spiegazioni scritte?
Gli esempi di codice vengono citati più spesso perché sono concreti e non ambigui. Però il codice senza spiegazione viene citato meno del codice con una chiara frase introduttiva. La documentazione più citata unisce spiegazioni chiare a esempi di codice funzionanti.
Devo permettere ai crawler AI di indicizzare la mia documentazione?
Sì, a meno che tu non abbia un motivo preciso per non farlo. Se la tua documentazione è un vantaggio competitivo e non vuoi che venga citata, puoi bloccare i crawler AI con il robots.txt. Ma la maggior parte delle API trae vantaggio dall'essere citata dai sistemi AI, perché porta traffico di sviluppatori qualificati. Bloccare i crawler significa che gli sviluppatori useranno API concorrenti più visibili nella ricerca AI.
Quali strumenti tecnici di GEO mi aiutano a controllare se la mia documentazione viene citata?
Usa strumenti di monitoraggio della visibilità AI per vedere quali pagine della tua documentazione vengono citate da ChatGPT, Perplexity, Claude e altri sistemi AI. Metti alla prova la tua documentazione a mano, chiedendo a ChatGPT e a Claude delle funzioni della tua API. Se la tua documentazione compare nelle risposte, l'ottimizzazione funziona. Se compaiono invece i concorrenti, hai del lavoro di ottimizzazione da fare.