> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.userbot.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.userbot.ai/_mcp/server. # Scrivere documenti che l'AI ritrova L'AI non legge i vostri documenti dall'inizio alla fine: ne recupera dei passaggi e risponde su quelli. Da questo discende tutto il resto di questa pagina. Un passaggio recuperato viene letto **fuori dal suo contesto**, senza il capitolo che lo precede e senza la pagina che lo segue. Se da solo non si capisce, la risposta sarà vaga anche con il documento giusto in archivio. Non puoi cambiare il modo in cui funziona il recupero. Puoi cambiare i documenti, ed è la leva più efficace che hai. ## Le sei regole ### 1. Metti titoli, e falli dire qualcosa Un titolo entra nel passaggio che lo segue e gli dà un appiglio. *«Preavviso di disdetta»* funziona; *«Art. 7»* no, perché nessuno cerca «articolo 7»: cerca «disdetta». Se un documento è un muro di testo senza intertitoli, aggiungerli è l'intervento con il miglior rapporto fra tempo speso e risposte migliorate. ### 2. Scrivi sezioni che si reggono da sole Ogni sezione dovrebbe ripetere il soggetto invece di rimandarlo. *«Il periodo di prova dura 14 giorni»* si capisce ovunque; *«dura 14 giorni»* recuperato da solo non dice a cosa. Vale soprattutto per le sezioni che iniziano con *«In questo caso…»*, *«Come sopra…»*, *«Vale lo stesso principio…»*: quando il passaggio arriva staccato, quel *«sopra»* non esiste più. ### 3. Dai alle tabelle un'intestazione vera Le tabelle vengono lette riga per riga. Se la prima riga contiene i nomi delle colonne, ogni riga recuperata resta comprensibile; se l'intestazione è una cella unita, o un titolo grafico sopra la tabella, le righe arrivano senza etichette e diventano numeri senza nome. Una colonna che si chiama *Valore* non aiuta nessuno. *Prezzo di listino 2026* sì. ### 4. Nei fogli, niente celle enormi Un foglio di calcolo viene diviso in blocchi di righe. Una singola riga troppo lunga (la cella con dentro il verbale della riunione, o la descrizione completa del prodotto) non entra in nessun blocco e **fa fallire l'indicizzazione dell'intero file**, non solo di quella riga. Se hai testi lunghi da conservare, tienili in un documento a parte e nel foglio mettici un riferimento. Un foglio serve a contenere dati, non paragrafi. ### 5. Non lasciare l'informazione dentro le immagini Userbot legge il testo dei file. Non guarda le figure, non interpreta gli schemi, non legge le scritte dentro uno screenshot, non apre le pagine scansionate. Un manuale con il testo corretto viene indicizzato bene, ma quello che è scritto solo dentro il diagramma non c'è. Quando un dato conta, come una soglia, una scadenza o un prezzo, scrivilo anche nel testo o in una didascalia. Vale la regola pratica: se l'informazione esiste solo come pixel, per l'AI non esiste. ### 6. Un documento, un argomento Il file *Varie 2026* con dentro il listino, la procedura di reso e i contatti dei fornitori dà risposte peggiori dei tre documenti separati, perché i suoi passaggi parlano di cose diverse e nessuno di loro è chiaramente «il» documento del listino. Quando dividi, dai a ogni file un nome che dica di cosa parla: il nome del file compare fra le fonti ed è la prima cosa che chi legge la risposta vede. ## Prima e dopo | Come si trova spesso | Come conviene metterlo | | --------------------------------------------------- | ------------------------------------------------------------------------- | | `Documento_finale_v3_DEF.pdf` | `Procedura resi, clienti business, 2026.pdf` | | Un PDF scansionato del contratto firmato | Il PDF originale con il testo, più la scansione come allegato di archivio | | Un foglio con una colonna *Note* da mille caratteri | Un foglio di dati, e le note in un documento collegato | | Un manuale di 200 pagine senza intertitoli | Lo stesso manuale con un titolo ogni due o tre pagine | | Tre listini con lo stesso nome e anni diversi | Un solo listino corrente in raccolta, gli altri in una cartella normale | > **Note** > > Il modo più rapido per verificare se un documento funziona è provarlo: apri > una chat, accendi **Ricerca nei documenti** sulla sua raccolta, fai la > domanda che i colleghi faranno davvero e guarda le **Fonti**. > Se il brano citato non è quello che ti aspettavi, il documento va sistemato, > non la domanda. ## Cosa non serve fare * **Non aggiungere parole chiave in fondo al documento.** La ricerca lavora sul significato: un elenco di sinonimi scollegato dal testo non aiuta e occupa un passaggio. * **Non tenere due versioni «per sicurezza».** Due documenti in contraddizione danno risposte in contraddizione. * **Non spezzare un documento in venti file minuscoli.** Il taglio in passaggi lo fa già Userbot: un file per argomento è la granularità giusta.