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 viaggio che nessuno ha pianificato
Per molto tempo, le relazioni con gli sviluppatori hanno seguito un percorso ben compreso. Si scriveva 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 mostrato che il 76% di tutti gli sviluppatori sta utilizzando o pianificando l'utilizzo di strumenti di intelligenza artificiale, con il 62% dei professionisti che li utilizzano attivamente giorno per giorno. Questi numeri erano già alti e da allora sono solo aumentati.
Il nuovo viaggio sembra 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 ha ora 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. È stato progettato esplicitamente in modo che gli assistenti AI possano accedere a sistemi esterni, estrarre il contesto e agire su di esso. La specifica lo descrive 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: è un linguaggio da infrastruttura, non da 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.
Le relazioni con gli sviluppatori sono state costruite per un'epoca diversa.
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 raggiungono 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.
Il costruttore si fida dell'AI. L'AI si fida della documentazione. Se la documentazione è vecchia, 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 nullo, che alla fine del fine settimana stavano inviando un 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 - e sta funzionando su una scala che lo rende davvero difficile da liquidare come un esperimento.
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 disegno 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 tipi di pubblico - lettori umani e 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 per risolvere con Rasepi: la scadenza forzata dei blocchi di documentazione, in modo che i contenuti obsoleti non possano nascondersi).
Il cambiamento silenzioso nel modo in cui vengono rappresentati i prodotti
C'è una conseguenza più ampia di tutto questo che vale la pena di affermare 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. Documenti obsoleti, ambigui, bloccati 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 seduto a Claude in questo momento, che descrive ciò che vuole costruire, aspettandosi 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'AI 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 e da Stack Overflow 2024 Developer Survey. La specifica /llms.txt è mantenuta su llmstxt.org. Il Model Context Protocol è documentato su modelcontextprotocol.io.