C'è una persona che in questo momento, da qualche parte, sta integrando la sua API. Non sono sul suo sito di documentazione. Non hanno aperto la sua guida introduttiva. Non hanno mai visto il suo parco giochi interattivo o la sua navigazione laterale accuratamente progettata.
Sono seduti in Claude. O Copilot. O in Cursor. Hanno digitato qualcosa come "integra l'API di fatturazione di Stripe con la mia applicazione Next.js utilizzando l'app router" e hanno atteso il ritorno del codice funzionante. L'AI ha letto i documenti per conto loro. Ha trovato gli endpoint pertinenti, ha compreso il flusso di autenticazione, ha scelto i metodi SDK giusti e ha prodotto un'implementazione.
Due settimane fa, allo Start Summit Hackathon di San Gallo, ho assistito a questo processo in tempo reale. Stavo parlando con un gruppo di studenti di informatica e un paio di fondatori di startup in fase iniziale su come approcciano le nuove API, e ognuno di loro ha descritto lo stesso flusso di lavoro: incollare il problema in un'intelligenza artificiale, ricevere il codice indietro, iterare da lì. Una delle studentesse ha riso quando le ho chiesto se avesse letto i documenti. "Perché dovrei? Claude li legge per me".
La persona non ha mai visitato il suo sito. Potrebbe non visitare mai il suo sito. E questo è sempre più spesso il modo in cui viene costruito il software.
Il cambiamento fondamentale
La documentazione oggi ha due consumatori fondamentalmente diversi: gli esseri umani che la leggono e gli assistenti AI che la leggono per conto dei costruttori. La maggior parte della documentazione è ottimizzata esclusivamente per gli esseri umani. L'AI è già il lettore dominante.
Questo cambia tutto a valle:
- Quando un'IA serve contenuti stantii, il costruttore non ha modo di rilevare il problema. Il danno si aggrava in modo silenzioso.
- I responsabili di prodotto, i progettisti e gli analisti stanno distribuendo software attraverso gli assistenti AI, spesso senza aver mai letto una riga di documentazione.
- La struttura leggibile dalla macchina è più importante del design visivo.** Un markdown pulito, blocchi autocontenuti e metadati espliciti sono ciò che consente all'AI di rappresentare il suo prodotto in modo accurato.
- I requisiti di formato si sono divisi.** I lettori umani hanno bisogno di narrazione. Gli intermediari dell'intelligenza artificiale hanno bisogno di specifiche strutturate e analizzabili. Lei deve servire entrambi.
Il resto di questo post spiega come siamo arrivati a questo punto, cosa significa per DevRel e cosa può fare in questo momento.
Il viaggio che nessuno ha pianificato
Per molto tempo, le relazioni con gli sviluppatori hanno seguito un percorso ben compreso. Avete scritto una documentazione completa. Ha pubblicato guide rapide. Ha tenuto conferenze. Ha mantenuto una presenza su Stack Overflow. Ha reso i suoi riferimenti API ricercabili, i suoi SDK idiomatici, i suoi messaggi di errore utili.
Questo percorso presupponeva che lo sviluppatore leggesse i suoi contenuti. Naviga nella sua struttura. Seguire i suoi passi.
Il sondaggio sugli sviluppatori 2024 di GitHub ha rilevato che il 97% degli sviluppatori aziendali ha utilizzato strumenti di codifica AI in qualche momento. Il sondaggio annuale di Stack Overflow ha evidenziato che il 76% di tutti gli sviluppatori sta utilizzando o pianificando l'utilizzo di strumenti di AI, con il 62% dei professionisti che li utilizzano attivamente giorno per giorno. Entro il 2026, questo numero salirà all'84%, con il 41% di tutto il codice ora generato dall'AI e il 51% degli sviluppatori professionisti che utilizzano quotidianamente gli strumenti di AI. Questi numeri non stanno rallentando.
Il nuovo viaggio ha un aspetto diverso. Qualcuno descrive ciò che vuole in linguaggio naturale. Un assistente AI legge la documentazione, trova le sezioni pertinenti e genera l'integrazione. Il costruttore esamina il risultato, forse perfeziona la richiesta, forse chiede un follow-up. Minuti, non ore.
L'imbuto di avvio che i team DevRel hanno perfezionato per anni? Viene aggirato. Non perché fosse sbagliato. Il punto di ingresso si è semplicemente spostato.
Due consumatori, una serie di documenti
La documentazione ora ha due destinatari fondamentalmente diversi.
Il primo è il lettore umano. Questa persona esiste ancora. Si presenta per le decisioni sull'architettura, il debugging dei casi limite, la revisione della conformità e la comprensione concettuale. Vogliono spiegazioni narrative, materiale di riferimento ben organizzato e un ragionamento chiaro sui compromessi.
Il secondo è l'intermediario AI. Legge la sua documentazione per conto di un costruttore. Non gli interessa la barra laterale. Non apprezza il suo design visivo. Ha bisogno di un contenuto strutturato, interpretabile dalla macchina: markdown pulito, formattazione coerente, specifiche esplicite su cui poter ragionare senza ambiguità.
Quasi tutti i siti di documentazione oggi sono ottimizzati esclusivamente per il primo pubblico. Il secondo pubblico è già il consumatore dominante.
Jeremy Howard ha identificato questa tensione quando ha proposto lo standard /llms.txt nel 2024. La sua osservazione era precisa: "I modelli linguistici di grandi dimensioni si basano sempre più sulle informazioni del sito web, ma devono affrontare una limitazione critica: le finestre di contesto sono troppo piccole per gestire la maggior parte dei siti web nella loro interezza." La proposta è semplice. Un file markdown curato in /llms.txt che fornisca ai modelli AI una panoramica strutturata del suo prodotto e i link alle risorse più importanti. FastHTML, i documenti di Anthropic e una crescente directory di progetti ne forniscono ora uno.
È una convenzione utile. Ma è anche un sintomo di un problema più profondo. Il vero problema non è il formato. È che la maggior parte della documentazione non è mai stata progettata pensando al consumo da parte delle macchine.
Il costruttore non sta tagliando le curve
C'è la tentazione di guardare la persona che richiede Claude invece di leggere la documentazione e concludere che sta prendendo delle scorciatoie. Che non capisce veramente cosa succede nel codice. Che sia in qualche modo uno sviluppatore inferiore.
Ho avuto questa conversazione abbastanza volte per sapere che di solito è sbagliata.
Molti di questi costruttori sono ingegneri senior che fanno scelte di efficienza deliberate. Capiscono il codice, ma non vogliono navigare in quattro pagine di documentazione per trovare le tre righe di cui hanno effettivamente bisogno. Hanno imparato che un assistente AI può estrarre quelle righe più velocemente di quanto possano fare loro, quindi delegano la lettura. (Onestamente, lo faccio anch'io. Non riesco a ricordare l'ultima volta che ho letto una guida introduttiva da cima a fondo).
Anthropic ha riconosciuto questo schema quando ha creato il Model Context Protocol. L'MCP è ora supportato da Claude, ChatGPT, VS Code, Cursor e altri. È esplicitamente progettato in modo che gli assistenti AI possano accedere a sistemi esterni, estrarre il contesto e agire su di esso. Le specifiche lo descrivono come in grado di fornire "l'accesso a un ecosistema di fonti di dati, strumenti e applicazioni che potenzieranno le capacità e miglioreranno l'esperienza dell'utente finale".
Lo legga attentamente. Si tratta di un linguaggio di infrastruttura, non di convenienza. I costruttori che utilizzano questi strumenti non stanno evitando il lavoro. Stanno lavorando attraverso un nuovo livello, e la sua documentazione fa parte di quel livello, che lei l'abbia progettato o meno.
I numeri lo confermano. La sola Claude gestisce oggi 25 miliardi di chiamate API al mese, con 30 milioni di utenti attivi mensili in 159 Paesi. Il 70% delle aziende Fortune 100 utilizza Claude. Secondo un sondaggio di Menlo Ventures, Anthropic detiene il 32% della quota di mercato dell'AI aziendale per utilizzo del modello, davanti a OpenAI con il 25%. Un rapporto di ricerca di HSBC lo colloca ancora più in alto: 40% della spesa totale in AI. Non si tratta di strumenti sperimentali. Sono infrastrutture primarie.
Le relazioni con gli sviluppatori sono state costruite per un'altra epoca.
Se la sua strategia DevRel è stata progettata prima del 2023, è stata pensata per un mondo in cui gli sviluppatori leggevano direttamente i documenti. Quel mondo non è scomparso, ma non è più il modello di interazione dominante per una quota crescente di costruttori.
Questo cambia il calcolo di diverse attività DevRel di lunga data.
**Una presentazione di 45 minuti ad una conferenza di sviluppatori raggiunge una sala di poche centinaia di persone. Un file /llms.txt ben strutturato e una documentazione pulita leggibile dalla macchina raggiungono ogni costruttore che chiede a qualsiasi assistente AI informazioni sul suo prodotto, continuamente, in qualsiasi momento. Il colloquio è un evento unico. La documentazione leggibile dalla macchina si compone. Non sto dicendo che le conferenze siano inutili (sono appena tornato da una di queste), ma l'equazione della leva è cambiata.
**Il classico tutorial di avvio rapido in cinque fasi è sempre più una formalità. Il costruttore non segue i passi. Descrive ciò che desidera e si aspetta che l'AI produca l'integrazione. Se l'API è ben documentata in un formato facile da usare, l'AI gestisce l'esperienza di avvio in modo più efficiente di quanto potrebbe fare qualsiasi tutorial. Le esercitazioni dovrebbero invece diventare materiale concettuale: spiegare perché scegliere l'approccio A rispetto all'approccio B. L'IA può generare l'implementazione. È molto meno affidabile nello spiegare i compromessi.
Stack Overflow. I dati del loro sondaggio mostrano che l'84% degli sviluppatori utilizza direttamente la documentazione tecnica, con il 90% di questi che si affida ai documenti all'interno dei pacchetti API e SDK. Ma il modo in cui accedono a questi documenti è sempre più spesso attraverso un livello AI, non una scheda del browser. Le domande che ancora arrivano a Stack Overflow tendono ad essere quelle difficili. Casi limite, debug di produzione, cose che richiedono sfumature. Preziose, certo. Ma non è più il luogo in cui si concentra il volume.
Quando l'AI legge i suoi documenti, la freschezza diventa fondamentale
Ecco la parte a cui la maggior parte dei team non ha pensato.
Quando un umano legge una pagina di documentazione, può applicare un giudizio. Potrebbe notare che le schermate sembrano vecchie, o che un commento in fondo dice che il processo è cambiato. Può strizzare l'occhio e pensare: "Sembra una cosa superata".
Un assistente AI non può fare nulla di tutto ciò. Legge il testo, lo elabora come fatto e genera una risposta con piena fiducia. Se la documentazione descrive un endpoint deprecato, l'AI consiglierà allegramente di integrarlo. Se la documentazione fa riferimento a un'infrastruttura che è stata sostituita sei mesi fa, l'AI descriverà la vecchia configurazione come attuale. Senza esitazioni.
Ed ecco la cosa che rende tutto questo peggiore di quanto sembri: Il 66% degli sviluppatori afferma già che il problema principale degli strumenti di AI è che forniscono risultati "quasi giusti ma non del tutto". La documentazione obsoleta alimenta direttamente questo problema. L'AI non ha le allucinazioni. Sta riproducendo fedelmente contenuti obsoleti e il costruttore non ha modo di capire la differenza.
Il costruttore si fida dell'AI. L'AI si fida della documentazione. Se la documentazione è obsoleta, questa catena di fiducia fornisce una risposta sicura e sbagliata.
Questo è sempre stato un problema, ovviamente. I contenuti obsoleti hanno sempre confuso le persone. Ma il danno era contenuto perché i lettori umani potevano a volte individuarlo. Gli intermediari AI non possono. Amplificano i contenuti stantii servendoli in scala, con autorità, a persone che non hanno motivo di dubitarne.
La freschezza non è più un problema di qualità dei contenuti. È un problema di affidabilità per ogni flusso di lavoro alimentato dall'AI che tocca i suoi documenti.
La parola "sviluppatore" è troppo ristretta
Le persone che costruiscono software nel 2026 non si identificano tutte come sviluppatori. Alcuni sono designer che chiedono a Claude di costruire un prototipo funzionante. Alcuni sono manager di prodotto che usano Cursor per distribuire strumenti interni. Alcuni sono analisti di dati che descrivono una pipeline di dati in linguaggio naturale e lasciano che un agente la assembli. Allo Start Summit, la metà dei team dell'hackathon aveva membri con un background di programmazione pari a zero, che alla fine del weekend stavano inviando software funzionante.
Ramp è un esempio utile. L'azienda fintech è passata da una valutazione di 5,8 miliardi di dollari nel 2023 a 32 miliardi di dollari entro la fine del 2025, superando il miliardo di dollari di fatturato annualizzato lungo il percorso. Una delle startup a crescita più rapida della storia. Una parte molto discussa del loro approccio: i product manager costruiscono le funzionalità direttamente con gli strumenti di AI, invece di aspettare in un backlog di ingegneria. I PM di Ramp non si limitano a scrivere le specifiche. Inviano il codice. L'AI gestisce l'implementazione. Il PM gestisce l'intento.
Non è una scorciatoia. Un nuovo modello operativo, che sta funzionando su una scala tale da rendere difficile liquidarlo come un esperimento.
Lo studio interno di Anthropic è rivelatore. Quando hanno intervistato 132 dei loro ingegneri su come utilizzano Claude, gli ingegneri hanno riferito di utilizzarlo per circa il 60% delle loro attività lavorative. Gli usi più comuni? Debuggare il codice esistente, capire cosa fanno le parti della base di codice e implementare nuove funzionalità. Gli ingegneri hanno detto che tendono a passare a Claude compiti "non complessi, ripetitivi, dove la qualità del codice non è critica". E il 27% del lavoro che svolgono ora con Claude semplicemente non sarebbe stato svolto prima.
Questo è il team di Anthropic. Le persone che hanno costruito il modello lo usano come lettore di documentazione, come navigatore della base di codice e come generatore di prime bozze. Tutti gli altri stanno facendo lo stesso, solo con la propria documentazione invece che con la loro.
Anthropic ha deciso di chiamare questa persona "costruttore". I loro strumenti sono progettati non solo per gli ingegneri informatici professionisti, ma per chiunque sia in grado di descrivere ciò che vuole costruire. Quando Claude può creare un'applicazione full-stack da un progetto Figma tramite MCP, la linea tradizionale tra "sviluppatore" e "non sviluppatore" si dissolve.
Questo ha implicazioni reali per chiunque gestisca la documentazione o si preoccupi dell'esperienza degli sviluppatori. Il suo pubblico non è più limitato alle persone che sanno cos'è un endpoint REST. Include tutti coloro il cui assistente AI potrebbe interagire con il suo prodotto. Il PM di Ramp che invia una funzionalità utilizzando la sua API? Probabilmente non leggerà mai direttamente la sua documentazione. Il loro agente AI lo farà assolutamente.
Cosa significa questo per la documentazione
Se la documentazione ora serve due pubblici, i lettori umani e gli intermediari AI, deve funzionare per entrambi. Sembra ovvio. In pratica, quasi nessuno lo fa.
Ecco cosa penso sia importante:
**Se i suoi documenti API sono una pagina HTML splendidamente renderizzata che un LLM deve analizzare e analizzare, l'AI sta lavorando più duramente di quanto dovrebbe. Spedisca la specifica OpenAPI grezza insieme alla versione renderizzata. Spedire un markdown pulito. Rendere le specifiche accessibili senza richiedere all'intelligenza artificiale di interpretare il layout della pagina.
**Gli assistenti AI non consumano la documentazione pagina per pagina. Estraggono le sezioni rilevanti. Un documento con intestazioni chiare, paragrafi autocontenuti e una semantica esplicita a livello di blocco è molto più utile per un'IA rispetto a una narrazione fluida che richiede la lettura dell'intera pagina per il contesto.
Segnali di fiducia che le macchine sanno leggere. Quando è stato rivisto l'ultima volta questo documento? È ancora attuale? Il contenuto è stato segnalato? Questi segnali devono esistere in una forma accessibile all'AI, non solo come indicazioni visive su una pagina web. Un punteggio di freschezza, uno stato di scadenza, una data di revisione, questi sono i metadati che permettono all'IA di decidere se un documento è sicuro da usare come fonte.
**Quando un assistente AI serve a un costruttore una risposta sicura basata su un endpoint deprecato, il danno è peggiore di un 404. Il costruttore ci costruisce sopra. Il costruttore ci costruisce sopra. Lo spedisce. Poi si rompe in produzione e nessuno sa perché, finché qualcuno non risale alla documentazione che avrebbe dovuto essere aggiornata mesi fa. Ogni documento a cui un'AI potrebbe fare riferimento ha bisogno di un meccanismo per dimostrare che è ancora aggiornato. (Questo è, in tutta franchezza, esattamente il problema che stiamo costruendo Rasepi per risolvere. La scadenza forzata dei blocchi di documentazione impedisce ai contenuti obsoleti di nascondersi).
Per iniziare: verificare la documentazione attuale
Se ha letto fino a questo punto e sta pensando "Ok, ma cosa devo fare effettivamente lunedì?", ecco quattro cose concrete che può controllare questa settimana.
1. Provi i suoi documenti attraverso un'AI. Apra Claude o ChatGPT e gli chieda di integrare il suo prodotto in uno scenario realistico. Non utilizzi le sue conoscenze interne. Guardi semplicemente ciò che l'AI produce. È corretto? È attuale? Utilizza i giusti endpoint, la giusta versione dell'SDK, il giusto flusso di autenticazione? Se l'AI sbaglia, è quello che i costruttori stanno ottenendo in questo momento.
**2. Scelga le cinque pagine di documentazione più visitate e si chieda: quando è stata fatta l'ultima revisione? Descrive ancora lo stato attuale del prodotto? Se non può rispondere con sicurezza, non può farlo nemmeno l'AI. Questa è la soluzione più efficace per la maggior parte dei team.
**3. Se non ha un file /llms.txt, ne crei uno. Se il suo riferimento API è disponibile solo come HTML renderizzato, esporti la specifica OpenAPI grezza e la renda accessibile. Se i suoi documenti si trovano in un CMS che non produce un markdown pulito, è un problema che vale la pena risolvere subito.
4. Aggiunga date di revisione e metadati di freschezza. Anche qualcosa di semplice, un campo last-reviewed nel suo sistema di gestione dei contenuti, un ciclo di revisione obbligatorio per le pagine ad alto traffico. In questo modo, sia gli esseri umani che l'intelligenza artificiale ricevono un segnale sull'affidabilità dei contenuti. Strumenti come Rasepi possono automatizzare questo aspetto con la scadenza forzata a livello di blocco, ma anche un processo manuale è meglio di niente.
Il cambiamento silenzioso nel modo in cui vengono rappresentati i prodotti
C'è una conseguenza più ampia di tutto questo che vale la pena di sottolineare direttamente.
La sua documentazione non è più solo un manuale di riferimento per gli sviluppatori. È il materiale di partenza che gli assistenti AI utilizzano per rappresentare il suo prodotto al mondo. Quando un costruttore chiede a Claude come utilizzare il suo prodotto, la risposta di Claude è modellata da tutto ciò che può trovare e analizzare nella sua documentazione.
Buona documentazione, buona risposta. Aggiornata, ambigua, bloccata all'interno di un HTML difficile da analizzare per un modello? Risposta peggiore o errata. Semplice.
La qualità della risposta dell'AI sul suo prodotto è ora un proxy diretto dell'esperienza dello sviluppatore. La maggior parte delle aziende non la sta ancora trattando in questo modo.
I team che sono all'avanguardia, Stripe, Vercel, Cloudflare, Anthropic stessa, trattano la leggibilità dell'AI come una preoccupazione di prima classe. Un requisito fondamentale che modella il modo in cui la documentazione viene scritta, strutturata e mantenuta. Non è una voce del backlog per il prossimo trimestre.
Il costruttore che siede in Claude in questo momento, descrivendo ciò che vuole costruire, si aspetta un codice funzionante in pochi minuti. Potrebbe non visitare mai più un sito di documentazione. Ma l'AI che li serve lo farà. Costantemente.
Questa AI è ora il suo lettore più frequente. La domanda è se la sua documentazione è pronta per questo.
La migliore strategia per l'esperienza dello sviluppatore nel 2026 non è una conferenza o una guida rapida. Si tratta di assicurarsi che l'IA faccia le cose per bene.
*Questo post fa riferimento a ricerche e documentazione di prodotto disponibili pubblicamente. Le statistiche sono tratte da GitHub's 2024 developer survey, Stack Overflow 2024 Developer Survey, Index.dev's 2026 developer productivity report, Incremys Claude statistics e Fortune's reporting on Anthropic. La specifica /llms.txt è mantenuta su llmstxt.org. Il protocollo Model Context è documentato su modelcontextprotocol.io.