TCDEV Blog

Lasci che il suo LLM pensi in inglese

2026-04-27T00:00:00Z

Lei invia un chatbot per il suo team tedesco. L'interfaccia utente è tedesca. I documenti di origine sono in parte tedeschi e in parte inglesi. Gli strumenti dietro l'assistente si aspettano valori enum in inglese, descrizioni di funzioni in inglese, nomi di prodotti in inglese, tutto in inglese.

Poi qualcuno fa una domanda perfettamente normale in tedesco, il modello sceglie lo strumento giusto, passa un argomento in tedesco invece che in inglese e l'intera faccenda va tranquillamente in pezzi.

Ho visto versioni di questo tipo abbastanza volte da non considerarlo più un problema di traduzione. Si tratta di un problema di esecuzione.

La mia impostazione attuale è semplice: lasciare che gli utenti parlino la lingua che desiderano, ma lasciare che l'LLM svolga il suo lavoro di reperimento, ragionamento e strumento in inglese quando l'affidabilità è effettivamente importante. Poi localizzare la risposta al di fuori di questo ciclo.

All'inizio sembra un po' eretico. Ma è anche, a mio avviso, la cosa più pratica che si possa fare in questo momento.

La ricerca sta iniziando a dirlo ad alta voce

I numeri non sono più sottili.

Nel benchmark MASSIVE-Agents, i ricercatori hanno valutato la chiamata di funzioni multilingue in 52 lingue, 47.020 campioni e 21 modelli. Il miglior punteggio medio in tutte le lingue è stato solo del 34,05%. L'inglese ha raggiunto il 57,37%. L'amarico è sceso al 6,81%.

Non si tratta di una piccola oscillazione della qualità. Si tratta di un precipizio di affidabilità.

Poi c'è [Lost in Execution] (https://arxiv.org/abs/2601.05366), che si avvicina ancora di più al problema dei sistemi reali. L'articolo mostra che molti fallimenti nella chiamata di strumenti multilingue avvengono dopo che il modello aveva già compreso l'intento e selezionato lo strumento corretto. Il problema dominante era la mancata corrispondenza linguistica dei valori dei parametri. In parole povere, il modello sapeva cosa fare, ma esprimeva i bit eseguibili nella lingua dell'utente invece che nella lingua dell'interfaccia, quindi la chiamata falliva comunque.

E questo non si limita alle chiamate agli strumenti. In Do Multilingual Language Models Think Better in English?, Etxaniz e colleghi hanno scoperto che l'auto-traduzione in inglese batteva in modo consistente l'inferenza diretta non inglese in cinque compiti. La loro formulazione è sorprendentemente schietta: i modelli non sono "in grado di sfruttare il loro pieno potenziale multilingue quando vengono sollecitati in lingue diverse dall'inglese".

Quindi sì, i modelli multilingue sono impressionanti. Ma se la vostra barra non è "sembra abbastanza buono" e invece è "deve comportarsi correttamente in produzione", l'inglese sembra ancora la lingua operativa più sicura molto spesso.

Perché RAG si rompe sempre nello stesso punto

Di solito le persone sentono questo argomento e pensano prima agli agenti. Chiamate di funzioni, output strutturato, esecuzione di API, questo genere di cose.

RAG ha la stessa debolezza, solo un livello prima.

Se il suo livello di reperimento deve abbinare il fraseggio locale di un utente a contenuti scritti in lingue miste, con una terminologia incoerente, nomi di prodotti tradotti ed etichette di tassonomia semilocalizzate, si creano più possibilità che il sistema vada alla deriva prima ancora di iniziare la generazione. Onestamente, è da qui che provengono molte delle lamentele "il modello è inaffidabile". Il modello può andare bene. L'interfaccia dei contenuti non lo è.

Preferirei normalizzare in anticipo.

Tradurre la domanda in inglese. Recuperare rispetto a un corpus canonico inglese. Lasciare che il modello ragioni su un livello terminologico stabile. Generare una bozza di risposta in inglese, se necessario. Poi traduce o localizza la risposta finale per l'utente.

In questo modo si ottiene un luogo in cui la denominazione rimane stabile:

un titolo di documento canonico
un vocabolario di prodotto canonico
uno schema di strumenti canonico
un insieme canonico di etichette di reperimento

È ancora possibile supportare ogni lingua dell'utente all'esterno. Basta smettere di chiedere al percorso di esecuzione principale di essere perfettamente multilingue in ogni fase.

Questo non è anti-localizzazione

Al contrario.

Una cattiva architettura AI multilingue di solito danneggia prima gli utenti locali. Ricevono la bella interfaccia localizzata, poi il sistema nascosto anglo-centrico sottostante si comporta in modo incoerente e fa pagare loro il prezzo.

Una localizzazione corretta significa essere onesti su dove la lingua deve flettersi e dove no.

Per me, la divisione è la seguente:

Localizzare l'interfaccia utente, i suggerimenti, il testo di aiuto, l'onboarding e le risposte finali.
Localizzare i contenuti di partenza che le persone leggono direttamente quando questi contenuti devono esistere sul mercato.
Mantenere le definizioni interne degli strumenti, gli identificatori canonici, le etichette di recupero e i perni di ragionamento in inglese, se questo è il livello più stabile.
Aggiungere una post-elaborazione esplicita o una revisione umana quando un risultato localizzato ha un peso legale, normativo o contrattuale.

Quest'ultimo punto è più importante di quanto i team amino ammettere. Se il modello sta parlando con un essere umano, la localizzazione è una decisione legata all'esperienza dell'utente. Se il modello sta parlando con un altro sistema, la lingua è un contratto di interfaccia.

Non sono la stessa cosa.

L'architettura di cui mi fido di più in questo momento

Questa è la versione su cui punterei oggi per i prodotti AI multilingue:

L'utente chiede nella sua lingua.
Il sistema traduce o normalizza la richiesta in inglese.
Il recupero, il ragionamento, la classificazione e le chiamate agli strumenti avvengono rispetto ai dati canonici inglesi.
La risposta finale viene localizzata nella lingua dell'utente.
I risultati ad alto rischio ricevono un'ulteriore fase di convalida prima di lasciare il sistema.

Non è filosoficamente puro. È sano dal punto di vista operativo.

L'aspetto positivo è che la ricerca recente punta nella stessa direzione. Lost in Execution ha scoperto che la pre-traduzione delle query degli utenti generalmente riduce gli errori di corrispondenza linguistica meglio delle correzioni post-hoc, anche se non recupera completamente le prestazioni a livello inglese. Questo corrisponde a ciò che molti costruttori già sospettano nella pratica. Se si aspetta fino alla fine per pulire l'incoerenza multilingue, di solito è troppo tardi.

E sì, ci sono delle eccezioni. Se si sta costruendo per lingue a bassa risorsa, per un linguaggio specifico del dominio o per un fraseggio culturalmente dipendente, tradurre tutto in inglese può introdurre una deriva. Il documento di cui sopra mette esplicitamente in guardia su questo aspetto. Quindi non trasformi questo in un dogma.

Ma come impostazione predefinita per i copiloti aziendali, gli assistenti interni, i RAG multilingue e gli agenti che utilizzano gli strumenti, credo che la regola sia sorprendentemente valida.

Cosa significa questo per Rasepi

Questo è esattamente il motivo per cui mi interessa tanto la struttura canonica dei contenuti.

Se la sua base di conoscenza ha un livello sorgente pulito, una terminologia stabile e una localizzazione controllata, l'AI diventa più facile da fidarsi. Se ogni versione linguistica va alla deriva in modo indipendente all'interno del percorso di esecuzione, si chiede al modello di improvvisare laddove il sistema dovrebbe essere preciso.

L'intero approccio di Rasepi si basa sulla separazione netta di queste preoccupazioni. Mantenere un nucleo canonico. Localizzare deliberatamente. Rintracciare dove esistono le varianti. Non pretenda che ogni livello dello stack sia ugualmente multilingue solo perché lo è l'interfaccia utente.

Un tempo pensavo che la migliore esperienza AI multilingue significasse "fare tutto nella lingua dell'utente". Non lo penso più. Non per i sistemi che devono recuperare il paragrafo giusto, scegliere lo strumento giusto e restituire qualcosa di cui ci si può fidare.

La regola pratica è semplice: gli utenti devono rimanere locali, ma il percorso di esecuzione dell'LLM deve rimanere stabile. Al momento, questo significa di solito l'inglese al centro e la localizzazione ai margini.

Questo cambierà nel tempo. Spero che cambi rapidamente. Ma se sta effettuando una spedizione oggi e l'affidabilità è più importante dell'estetica, lascerei che il modello pensi in inglese e che il suo prodotto parli la lingua dell'utente.

Claude Design e l'agenzia creativa individuale

2026-04-18T00:00:00Z

Ieri Anthropic ha lanciato Claude Design, un nuovo prodotto del team Anthropic Labs che consente di creare progetti, prototipi, presentazioni e materiale di marketing parlando con Claude. E mi sono seduto a guardare l'annuncio pensando: ok, ora una persona con un abbonamento a Claude ha davvero la maggior parte di ciò che offre una piccola agenzia creativa. Design. Codice. Automazione. Presentazioni. Coerenza con il marchio. Tutto all'interno dello stesso ecosistema.

È una frase azzardata da scrivere nel 2026. Ma non credo che sia un'esagerazione.

Cosa fa il Claude Design

La versione breve: lei descrive ciò di cui ha bisogno e Claude costruisce una prima versione. Poi la perfeziona attraverso la conversazione, i commenti in linea, le modifiche dirette o i cursori personalizzati che Claude genera per lei. Si basa su Opus 4.7 ed è sorprendentemente bravo a mantenere la coerenza visiva.

Ma la caratteristica che ha attirato la mia attenzione è l'onboarding. Durante la configurazione, Claude legge la sua base di codice e i file di progettazione esistenti per costruire un sistema di progettazione per il suo team. Colori, tipografia, componenti. Ogni progetto successivo segue automaticamente il suo marchio. Può importare immagini, documenti (DOCX, PPTX, XLSX) o puntare direttamente alla sua base di codice. C'è uno strumento di acquisizione web che cattura gli elementi dal suo sito web reale, in modo che i prototipi assomiglino al prodotto reale.

Ha un mockup di Figma su cui vuole iterare? Lo esporti, lo inserisca in Claude Design e inizi una conversazione su cosa cambiare. O semplicemente catturare il suo sito web esistente e dire "rendi la sezione eroe più grande e aggiungi un carosello di testimonianze". Questo genere di cose.

Le testimonianze dell'annuncio sono eloquenti. Il Senior Product Designer di Brilliant ha detto che le loro pagine più complesse, che richiedevano 20+ richieste per essere ricreate in altri strumenti, hanno richiesto solo 2 richieste in Claude Design. Il Product Manager di Datadog ha descritto il passaggio da un'idea grezza a un prototipo funzionante prima che qualcuno lasci la stanza, e ha detto che ciò che prima richiedeva una settimana di briefing, mockup e revisioni, ora avviene in una sola conversazione.

Una settimana di tira e molla, racchiusa in un'unica conversazione. Ci pensi per un attimo.

Lo stack che cambia tutto

Ecco dove il discorso si fa interessante. Il Claude Design non esiste in modo isolato. Anthropic ha ora tre prodotti che, combinati, coprono una quantità assurda di terreno:

Claude Code: Scrivere, revisionare e spedire il software vero e proprio. 2,5 miliardi di dollari di entrate correnti a febbraio, responsabile di circa il 4% di tutti i commit pubblici di GitHub in tutto il mondo.
Claude Cowork: Automatizza il lavoro di conoscenza. Ricerca, analisi, elaborazione di documenti, attività ricorrenti dal suo desktop.
Claude Design: Crea lavori visivi. Prototipi, presentazioni, materiale di marketing, beni coerenti con il marchio.

E si passano la mano l'un l'altro. Quando un progetto è pronto per essere costruito, Claude impacchetta tutto in un pacchetto di consegna che può passare a Claude Code con un'unica istruzione. Dal design alla produzione in un unico flusso. Nessun ticket Jira. Nessuna riunione di handoff. Niente "puoi inviarmi le specifiche in Slack".

Continuo a pensare alla previsione di Sam Altman dell'inizio del 2024 su l'azienda unipersonale da un miliardo di dollari. All'epoca sembrava un'aspirazione, forse un po' iperbolica. Gli strumenti non erano ancora disponibili. Si potevano generare testi e immagini, certo, ma il divario tra la generazione di cose e la spedizione di prodotti reali era enorme.

Questo divario si sta riducendo rapidamente.

Cosa avrei dato per questo due mesi fa

Quando ho costruito Rasepi, il sito di marketing era una delle parti più noiose. Non il codice. Il codice andava bene, Claude gestisce HTML e CSS come un campione. Ma le decisioni sul design visivo? Il layout degli eroi, le schede delle pagine dei prezzi, le tabelle di confronto delle funzionalità? Ho descritto le cose a parole, Claude ha prodotto qualcosa, e poi ho passato ore a fare avanti e indietro cercando di regolare la spaziatura, i colori, la tipografia. Il tutto tramite messaggi di testo. Nessun ciclo di feedback visivo.

Con Claude Design, questo flusso di lavoro diventa: "Ecco il mio sito web" (acquisizione web), "ridisegna la sezione dei prezzi per enfatizzare il piano del team" (conversazione), modifica il colore verde dell'accento con un cursore, approvazione, consegna a Claude Code per l'implementazione. Credo che questo mi avrebbe fatto risparmiare un intero fine settimana.

(Onestamente, sono un po' seccato che non sia stato lanciato due mesi prima).

E l'esportazione di Canva è intelligente. Canva ha 220 milioni di utenti attivi e 3 miliardi di dollari di fatturato annuo. Anthropic non sta cercando di sostituire Canva. Sta cercando di essere il luogo in cui le idee iniziano prima di approdare a Canva per la rifinitura finale e la distribuzione. Si tratta di un gioco di posizionamento intelligente. Si genera la creatività in Claude Design, poi si esporta in Canva dove il team di marketing la raccoglie. Oppure esporta in PPTX per quel mazzo per gli investitori. Oppure esportare come HTML autonomo per una landing page.

Il moltiplicatore "basta aggiungere strumenti

Questo è lo schema che continuo a vedere nello spazio AI nel 2026. Il modello di base diventa più intelligente, certo, ma il vero salto di produttività si ottiene collegando gli strumenti tra loro. Claude da solo è un generatore di testo molto intelligente. Claude con Code è un ingegnere software. Claude con Cowork è un analista di ricerca. Claude con Design è un direttore creativo. Claude con tutti e tre? È una piccola agenzia.

E le connessioni continuano a crescere. Anthropic ha dichiarato che aggiungerà altre integrazioni nelle prossime settimane. I server MCP consentono già di collegare Claude a strumenti e fonti di dati esterni. L'ecosistema si sta costruendo da solo.

Per i fondatori solitari, i freelance e i piccoli team, questo cambia completamente il calcolo. Non ha bisogno di un designer a pagamento per produrre documenti e prototipi dall'aspetto professionale. Non ha bisogno di uno sviluppatore frontend separato per trasformare i mockup in codice. Non ha bisogno di un project manager per coordinare il passaggio tra design e ingegneria, perché non c'è nessun passaggio. Si tratta di una conversazione continua.

Non sto dicendo che i designer sono obsoleti. Tutt'altro. Brilliant e Datadog hanno entrambi descritto i loro progettisti utilizzando Claude Design. Lo strumento rende i bravi designer più veloci e consente a tutti gli altri di accedere a risultati visivi competenti. È una cosa diversa dal sostituire le persone.

Cosa significa questo per i prodotti di documentazione

Questo aspetto lo osservo da vicino. In Rasepi, stiamo costruendo una piattaforma di documentazione in cui la qualità visiva è importante. Le pagine di ingresso devono essere belle. Le guide rapide devono avere diagrammi chiari. I documenti di marketing devono essere coerenti con il marchio tra le varie lingue e i vari team.

Un mondo in cui ogni membro del team può generare una documentazione visiva in linea con il marchio, consegnarla al motore di traduzione e distribuirla in sette lingue senza toccare Figma, Photoshop o InDesign? Questo è esattamente il problema che stiamo risolvendo da un'altra angolazione. (E sì, questo è esattamente il tipo di flusso di lavoro che Rasepi è costruito per supportare).

La parte in cui diventa stranamente costosa

Ecco la cosa di cui nessuno parla ancora. Ho creato un nuovo account Anthropic appositamente per provare Claude Design. Account nuovo, nessuna storia, nessun utilizzo precedente. Ho importato un piccolo file Figma e ho generato una singola risorsa. Tutto qui. Due operazioni. E ho finito i crediti.

Su un conto nuovo di zecca. Con una nuova allocazione.

Non so come sia il calcolo dei token da parte di Anthropic quando Opus 4.7 si occupa della generazione visiva, ma qualunque cosa sia, brucia i crediti a un ritmo che fa sembrare il lancio di "agenzia creativa per una sola persona" molto più costoso del previsto. Se l'importazione di un piccolo mockup Figma e la produzione di un'immagine consumano l'intero budget, l'economia dell'utilizzo di questo strumento di design quotidiano non funziona ancora.

Per essere onesti, questa è un'anteprima di ricerca e i prezzi probabilmente cambieranno. Ma al momento c'è un divario significativo tra la promessa (sostituire il suo flusso di lavoro di progettazione) e la realtà (potrebbe esaurire i crediti prima di pranzo). I guadagni di produttività sono reali. Se il rapporto crediti per output lo renda pratico per un uso regolare è una questione completamente diversa.

L'avvertimento onesto

Claude Design è in anteprima di ricerca. Avrà degli spigoli vivi. Le testimonianze provengono da team di progettazione di aziende ben finanziate con sistemi di progettazione consolidati. Il suo chilometraggio varierà, soprattutto se sta iniziando da zero, senza linee guida del marchio che lo alimentino.

Ma la traiettoria è chiara. Diciotto mesi fa erano necessari un designer, uno sviluppatore e un project manager per passare dall'idea alla pagina di destinazione spedita. Oggi una sola persona con un abbonamento a Claude può realizzare una versione sorprendentemente credibile dello stesso flusso di lavoro in un pomeriggio.

Non siamo ancora alla società miliardaria composta da una sola persona. Ma l'agenzia creativa composta da una sola persona? Penso che siamo appena arrivati.

Una chiave API, molti inquilini: Come isoliamo le traduzioni di DeepL tra i vari clienti

2026-04-18T00:00:00Z

C'è una domanda che sorge ogni volta che spiego l'architettura di traduzione di Rasepi ad un altro sviluppatore: "Aspetti, quindi tutti i suoi inquilini condividono una chiave API DeepL? Come fa a evitare che i loro glossari e le loro regole di stile si influenzino a vicenda?".

È una domanda giusta. E la risposta comporta più lavoro di progettazione di quanto ci si aspetti.

Abbiamo trattato la pipeline di traduzione completa in un post precedente, l'hashing a livello di blocco, l'orchestratore, l'intero flusso dal salvataggio del documento all'output tradotto. Questo post si concentra sul problema specifico della multi-tenancy. Come prendere un'API di terze parti che non ha un concetto di locatari e costruirci sopra l'isolamento dei locatari.

Il problema: DeepL non conosce i suoi clienti

L'API di DeepL si autentica con una singola chiave API. Tutto ciò che viene creato con quella chiave, glossari, elenchi di regole di stile, cronologia delle traduzioni, appartiene allo stesso account. Non esiste il concetto di "questo glossario appartiene all'inquilino A" da parte di DeepL.

Quando chiama GET /v2/glossaries, ottiene tutti i glossari di tutti gli inquilini. Quando crea un elenco di regole di stile, questo vive nello stesso spazio dei nomi delle regole di stile di ogni altro inquilino. L'API è piatta.

Per un prodotto self-hosted in cui ogni cliente gestisce la propria istanza con la propria chiave DeepL, questo va bene. Per un SaaS multi-tenant in cui gestiamo l'infrastruttura? È necessario un livello di isolamento.

Il database è la fonte della verità

La nostra decisione progettuale principale: il database possiede tutti i contenuti del glossario e la configurazione delle regole di stile. DeepL è un obiettivo di esecuzione in fase di runtime, niente di più.

Ogni entità TenantGlossary e TenantStyleRuleList implementa ITenantScoped, il che significa che i filtri delle query globali di EF Core estendono automaticamente tutte le letture al tenant corrente. Una query per i glossari nel contesto di richiesta del tenant A non restituirà mai le voci del tenant B. Questo è lo stesso modello di isolamento che utilizziamo ovunque in Rasepi, applicato a livello di ORM.

Ecco cosa rende questo interessante. Quando un inquilino modifica un termine del glossario, non chiamiamo immediatamente DeepL. Aggiorniamo la riga del database e impostiamo IsDirty = true. Questo è tutto. Il glossario effettivo DeepL viene creato (o ricreato) pigramente, proprio prima che la traduzione successiva ne abbia bisogno.

public async Task<string?> GetOrSyncDeepLGlossaryIdAsync(
    string sourceLanguage, string targetLanguage)
{
    var glossary = await _db.TenantGlossaries
        .Include(g => g.Entries)
        .FirstOrDefaultAsync(g =>
            g.SourceLanguage == sourceLanguage &&
            g.TargetLanguage == targetLanguage);

    if (glossary?.Entries.Count == 0) return null;

    if (!glossary.IsDirty && glossary.DeepLGlossaryId is not null)
        return glossary.DeepLGlossaryId;

    // Dirty: delete old, create new
    if (glossary.DeepLGlossaryId is not null)
        await _deepL.DeleteGlossaryAsync(glossary.DeepLGlossaryId);

    var entries = glossary.Entries
        .ToDictionary(e => e.SourceTerm, e => e.TargetTerm);

    var created = await _deepL.CreateGlossaryAsync(
        $"rasepi-{glossary.Id}",
        glossary.SourceLanguage,
        glossary.TargetLanguage,
        entries);

    glossary.DeepLGlossaryId = created.GlossaryId;
    glossary.IsDirty = false;
    glossary.LastSyncedAt = DateTime.UtcNow;
    await _db.SaveChangesAsync();

    return glossary.DeepLGlossaryId;
}

Il filtro di query su TenantGlossaries fa l'isolamento. Il flag IsDirty fa la sincronizzazione pigra. E la convenzione di denominazione (rasepi-{glossary.Id}) serve solo per il debug nella dashboard DeepL, non ha alcuno scopo funzionale.

Perché pigro? Perché i glossari di DeepL v2 sono immutabili. Non è possibile modificarli. Qualsiasi modifica significa cancellare e ricreare. Se un team importa un CSV con 200 termini e poi corregge un refuso in una voce, non vogliamo cancellare e ricreare il glossario DeepL due volte. Basta impostare IsDirty in entrambe le occasioni e la singola ricreazione avviene quando viene eseguita la traduzione successiva.

Regole di stile: stesso modello, API diversa

Le regole di stile di DeepL sono più recenti (API v3) e sono effettivamente mutabili, il che è più bello. Può aggiornare le regole configurate in loco con PUT /v3/style_rules/{style_id}/configured_rules, e le istruzioni personalizzate possono essere aggiunte o rimosse individualmente.

Tuttavia, utilizziamo ancora lo stesso schema IsDirty. Un TenantStyleRuleList ha un DeepLStyleId che corrisponde all'identificatore di runtime di DeepL, più ConfiguredRulesJson per le regole di formattazione e una collezione di voci TenantCustomInstruction per le direttive di traduzione a testo libero.

La vera potenza è in queste istruzioni personalizzate. Ognuna di esse è una direttiva in linguaggio semplice, fino a 300 caratteri, che modella il modo in cui DeepL traduce. Esempi reali dai nostri inquilini:

"Utilizzi sempre la forma 'Sie', mai 'du'" per uno studio legale tedesco.
"Traduca 'deployment' come 'Bereitstellung', mai 'Deployment'" per termini dipendenti dal contesto che vanno oltre le semplici mappature del glossario.
"Utilizzi l'ortografia inglese britannica (colore, organizzazione, licenza)" per un'azienda del Regno Unito che traduce tra le varianti inglesi
"Metta i simboli di valuta dopo l'importo numerico" per le convenzioni europee

Ogni locatario può avere istruzioni completamente diverse per ogni lingua di destinazione, tutte dietro la stessa chiave API. L'isolamento deriva dal fatto che ogni chiamata di traduzione include solo i glossary_id e style_id appartenenti al tenant richiedente. Le risorse DeepL di altri tenant non vengono mai citate.

La chiamata di traduzione: tutto si compone

Quando l'orchestratore traduce un blocco, assembla tutte le impostazioni specifiche del tenant in un'unica richiesta:

var glossaryId = await _glossaryService
    .GetOrSyncDeepLGlossaryIdAsync(sourceLang, targetLang);
var styleId = await _styleRuleService
    .GetOrSyncStyleIdAsync(targetLang);
var formality = langConfig.Formality ?? "default";

var options = new TranslationOptions
{
    GlossaryId = glossaryId,
    StyleId = styleId,
    Formality = formality,
    Context = documentContext,
    ModelType = styleId != null ? "quality_optimized" : null
};

Tutti i parametri qui sono in base all'inquilino. Il glossaryId è stato risolto attraverso una query filtrata dall'inquilino. Il styleId è stato risolto allo stesso modo. Il formality proviene da TenantLanguageConfig, anch'esso in base al tenant-scoped. Anche il context (paragrafi circostanti inviati per migliorare la qualità della traduzione, non fatturati) proviene dal documento del locatario.

Una cosa che voglio sottolineare: quando style_id è impostato, DeepL utilizza automaticamente il loro modello quality_optimized. Non è possibile combinare le regole di stile con latency_optimized. Si tratta di un vincolo di DeepL, ma onestamente ragionevole. Se sta investendo in regole di stile personalizzate, probabilmente vuole un risultato della migliore qualità.

Caching a livello di blocco: il database come memoria di traduzione

Non chiamiamo DeepL per i blocchi che non sono stati modificati. Il meccanismo di caching è la tabella TranslationBlock stessa.

Ogni EntryBlock sorgente ha un ContentHash, una SHA256 del suo contenuto semantico (con attributi di metadati come blockId e deleted eliminati). Ogni TranslationBlock memorizza il SourceContentHash corrente al momento della traduzione. Quando il blocco sorgente cambia, cambia anche il suo hash. L'orchestratore confronta gli hash e accoda solo i blocchi che non corrispondono.

L'albero decisionale per ogni blocco si presenta come segue:

Corrispondenza hash, traduzione esistente = salta (memorizzato nella cache, aggiornato)
Hash cambiato, traduzione automatica, non bloccato = ritraduce automaticamente
Hash modificato, modificato dall'uomo o bloccato = contrassegnare come Stale, non sovrascrivere

Il terzo caso è fondamentale. Se il suo traduttore tedesco rifinisce manualmente un paragrafo, non lo sovrascriviamo solo perché la fonte inglese è cambiata. Lo contrassegniamo come stantio, in modo che sappiano che deve essere rivisto, ma il testo tradotto rimane intatto.

Il risultato pratico: la modifica di un paragrafo in un documento di 30 paragrafi attiva esattamente una chiamata API DeepL (beh, un lotto che include un blocco). Gli altri 29 paragrafi, in tutte le lingue, sono già memorizzati nella cache e non costano nulla.

Perché non utilizzare una chiave separata per ogni inquilino?

Ci ho pensato seriamente. Dare a ciascun inquilino la propria chiave API DeepL, eliminando completamente il problema dell'isolamento.

Tre motivi per non farlo:

**Ogni inquilino avrebbe avuto bisogno di un proprio abbonamento a DeepL o di un modo per fornire sub-account. DeepL non offre la gestione delle chiavi multi-tenant in modo nativo.
Efficienza dei costi. L'infrastruttura condivisa significa limiti tariffari e sconti sul volume condivisi. Il nostro utilizzo aggregato consente di ottenere prezzi migliori.
**Una sola chiave da ruotare, una sola quota da monitorare, una sola integrazione da mantenere.

Il compromesso è che abbiamo bisogno del livello di isolamento che ho descritto. Ma dato che abbiamo già delle query EF Core con scala per inquilino per tutto il resto del sistema, l'aggiunta ai glossari e alle regole di stile è stata semplice. Il modello era già presente.

Cosa protegge effettivamente

Per riassumere le garanzie di isolamento:

Le voci del glossario** sono memorizzate in TenantGlossary (implementa ITenantScoped), filtrate dai filtri di query globali di EF Core. DeepL Gli ID del glossario sono riferimenti opachi che vengono risolti solo nel contesto dell'inquilino.
Le regole di stile e le istruzioni personalizzate seguono lo stesso schema attraverso TenantStyleRuleList.
Il contenuto tradotto risiede in TranslationBlock, con uno scope attraverso la catena del suo genitore Entry → Hub, anch'esso con uno scope da inquilino.
La guardia SaveChanges imposta TenantId automaticamente sulle nuove entità e lancia le scritture cross-tenant.
Nessun IgnoreQueryFilters()** nel codice di produzione. Mai.

Il principio di progettazione è semplice: DeepL vede gli ID delle risorse. Rasepi vede le entità con scala di inquilino. La mappatura tra loro non attraversa mai i confini degli inquilini, perché la query che risolve la mappatura è fisicamente incapace di restituire i dati di un altro inquilino.

Se sta costruendo un SaaS multi-tenant che si integra con API di terze parti senza supporto nativo del tenant, questo modello funziona bene. Tratta l'API esterna come un motore di esecuzione stateless, conserva tutta la configurazione nel suo database con scala tenant, sincronizza in modo pigro e non si affida mai agli elenchi di risorse esterne per l'isolamento.

I gettoni bruciati sono le nuove linee di codice

2026-04-13T00:00:00Z

Il mio feed di LinkedIn ne è pieno da settimane. Anche la mia timeline X. Persone che pubblicano schermate di spesa di token come se fossero relazioni sui progressi. Fondatori di startup che si vantano di aver speso 16.000 dollari in Claude Code il mese scorso e di puntare a 60.000 dollari il prossimo. Classifiche. Classifiche. Titoli come "Token Legend" e "AI God".

E poi, la scorsa settimana, ha raggiunto la massa critica. Forbes ha riferito del movimento "tokenmaxxing" che sta travolgendo la Silicon Valley, dove le aziende competono per vedere chi brucia più token AI. Jensen Huang ha partecipato al podcast All-In e ha detto: "Quell'ingegnere da 500.000 dollari, alla fine dell'anno, gli chiederò: "Quanto hai speso in token?". Se quella persona mi risponde '5.000 dollari', io mi sclerotizzo. Se quell'ingegnere da 500.000 dollari non ha consumato almeno 250.000 dollari di token, mi allarmerò profondamente".

Poi Fortune ha riportato che un dipendente di Meta ha costruito una classifica interna chiamata "Claudeonomics", che tiene traccia del consumo di token da parte degli oltre 85.000 dipendenti dell'azienda. I migliori utenti ricevevano dei titoli. In un periodo di 30 giorni, l'utilizzo totale ha raggiunto i 60.000 miliardi di token. Il singolo utente migliore ha avuto una media di 281 miliardi. Mark Zuckerberg non è nemmeno entrato nella top 250. Il CTO di Meta Andrew Bosworth, nel frattempo, ha dichiarato pubblicamente che il suo miglior ingegnere spendeva l'equivalente del suo stipendio in token, ma era "da 5 a 10 volte più produttivo". "È come se fossero soldi facili", ha detto Bosworth. "Senza limiti".

Lavoro nel software da abbastanza tempo per capire cosa sta succedendo. Si tratta di "linee di codice" con un prezzo molto più alto.

Ci siamo già passati

Nel 2003, Martin Fowler ha scritto un breve articolo sul perché la produttività del software non può essere misurata che probabilmente dovrebbe essere una lettura obbligatoria per ogni dirigente tecnico. La sua argomentazione sulle linee di codice era precisa:

"Una delle mie maggiori irritazioni sono gli studi sulla produttività basati sulle linee di codice. Ogni buon sviluppatore sa che può codificare le stesse cose con enormi variazioni di linee di codice".

Il problema è evidente quando lo si dice ad alta voce. La LOC misura l'attività, non la produzione. Due sviluppatori possono costruire la stessa funzione: uno scrive 1.200 righe, l'altro ne scrive 80. Il più conciso probabilmente ha costruito una funzione migliore. Quello più conciso probabilmente costruisce un sistema migliore. In un regime di LOC, il verboso sembra più produttivo.

I team valutati in base al LOC hanno risposto in modo razionale. Hanno scritto più righe. Hanno fatto copia-incolla invece di astrarre. Hanno evitato il refactoring, perché l'eliminazione del codice avrebbe danneggiato i loro numeri. La metrica ha modellato il comportamento, ma non verso un software migliore. Più codice. Sistemi peggiori.

Poi, nel 2023, McKinsey pubblicò un articolo in cui sosteneva di aver decifrato la misurazione oggettiva della produttività degli sviluppatori. La risposta approfondita di Gergely Orosz e Kent Beck ha evidenziato lo stesso difetto: quasi tutte le metriche di McKinsey misuravano lo sforzo e la produzione, non i risultati. Kent Beck ha raccontato di aver visto i sondaggi interni di Facebook sul sentiment degli sviluppatori trasformarsi da un feedback utile a una negoziazione dei manager con gli ingegneri per ottenere punteggi più alti. Ecco cosa succede quando si incentiva una metrica proxy. Il numero migliora. La cosa di cui ci si preoccupa veramente non migliora.

Si potrebbe pensare che abbiamo imparato. Non è così.

Stesso errore, unità diversa

La logica seducente del tokenmaxxing funziona così. Consumo di gettoni = utilizzo dell'AI. Più utilizzo dell'AI = i team utilizzano l'AI. Pertanto, un'elevata spesa di token = un'elevata adozione dell'IA = buona.

Si tratta di una logica errata come quella di misurare le linee di codice, ma con un cruscotto di fatturazione invece di un grafico di commit. E per essere corretti nei confronti dell'articolo di Forbes, il CEO di Sendbird, John Kim, ha detto esattamente questo: "Abbiamo già visto questo film". Si riferiva alla cultura LOC degli anni '90 e 2000. Il vero indicatore, ha osservato, è la quantità di codice generato dall'AI che entra effettivamente in produzione. La spesa per i gettoni "è più che altro un argomento di conversazione". Sono d'accordo. Diventa un problema quando l'argomento di conversazione viene promosso a KPI principale.

Il sondaggio sugli sviluppatori 2024 di GitHub ha rilevato che il 97% degli sviluppatori aziendali ha utilizzato strumenti di codifica AI sul lavoro in qualche momento. Un'adozione organizzativa significativa, tuttavia, richiede politiche chiare, flussi di lavoro e risultati misurabili legati ai risultati aziendali effettivi. Non solo utilizzo. Non solo consumo.

Boris Cherny, l'ingegnere che sta dietro a Claude Code, ha condiviso pubblicamente che non ha aperto alcun IDE durante un mese di lavoro, con Opus 4.5 che ha scritto circa 200 PR. È impressionante. Ma ciò che lo rende impressionante non sono i token che quei 200 PR hanno consumato. È che si trattava di 200 contributi reali uniti con un software funzionante all'altro capo.

Il valore è nel risultato. I gettoni sono l'energia che ha portato al risultato, niente di più.

Quando la metrica diventa l'obiettivo

Esiste un principio chiamato Legge di Goodhart: quando una misura diventa un obiettivo, cessa di essere una buona misura. La storia dello sviluppo del software è praticamente un museo della Legge di Goodhart in azione.

Il monitoraggio dei token come KPI per l'adozione dell'AI crea la stessa dinamica. I team di ingegneri misurati sul consumo di token consumeranno più token. È così che funzionano gli incentivi. Vuole sembrare più produttivo? Esegua qualche ciclo agenziale in più. Lasci che il modello ragioni a lungo prima di generare l'output. Avvolgere ogni attività in un livello di orchestrazione che richiama quattro strumenti dove ne basterebbe uno. La spesa in gettoni aumenta. Il valore fornito non aumenta.

In realtà, la storia di Claudeonomics lo ha dimostrato quasi subito. Fortune ha notato che "alcuni dipendenti hanno messo gli agenti AI al lavoro per ore per massimizzare l'utilizzo dei token". Eccola qui. La Legge di Goodhart in esecuzione in tempo reale, all'interno di un'azienda che dovrebbe essere alla frontiera della produttività guidata dall'AI. La classifica era attiva da qualche settimana prima di essere chiusa, e i dipendenti la stavano già sfruttando eseguendo agenti in loop. La metrica era vecchia di tre settimane e aveva già smesso di misurare ciò che doveva misurare.

Ogni sviluppatore che legge questo articolo può probabilmente pensare a cinque modi per gonfiare le metriche di utilizzo dei token senza alcun beneficio per nessuno. Non li elencherò. Ma se a me ne vengono in mente cinque, possono farlo anche gli ingegneri che vengono misurati in questo caso.

Andrej Karpathy ha descritto il momento attuale dell'ingegneria del software come un "terremoto di magnitudo 9" per la professione. Ha ragione. Ma i terremoti non si misurano in base all'elettricità consumata. Si misurano in base a ciò che si è mosso.

La versione della documentazione di questo problema

Questo non è un problema solo per i team di ingegneri. Vedo la stessa dinamica nella gestione della conoscenza, che è molto più vicina a noi di Rasepi.

"Abbiamo pubblicato 400 documenti in questo trimestre" è un numero che suona bene in una presentazione. Non ha nulla a che vedere con l'accuratezza di quei documenti, con il fatto che qualcuno li abbia letti o che le informazioni in essi contenute siano ancora vere sei mesi dopo. È possibile ottenere quel numero con l'AI e senza alcun pensiero. Rumore assistito da token pubblicato su scala.

La metrica onesta è più difficile da raccogliere, ma molto più utile: quale percentuale della sua base di conoscenza riflette effettivamente il funzionamento dei suoi sistemi oggi? Quante persone hanno raggiunto una risposta corretta utilizzando la sua documentazione? Quanti ci hanno provato, hanno fallito e hanno finito per chiedere a qualcuno su Slack?

Queste domande non hanno ancora dei bei dashboard. Richiedono una riflessione concreta su ciò che vuole che la documentazione faccia per la sua organizzazione. (Non a caso, questo è esattamente il problema su cui si basa Rasepi. Le date di scadenza forzate esistono proprio perché i team debbano valutare se i contenuti sono ancora validi, piuttosto che lasciarli decadere silenziosamente dietro una metrica di numero di pagine elevato).

Cosa monitorare invece

La risposta onesta alla domanda "il nostro investimento nell'AI sta dando i suoi frutti?" non può essere letta da un cruscotto di fatturazione.

Si può approssimare con domande migliori: i tempi di ciclo stanno migliorando? Il rapporto tra le funzionalità consegnate e i bug segnalati è in tendenza nella giusta direzione? Gli ingegneri riferiscono di dedicare più tempo al lavoro di valutazione e meno alla digitazione? La sua documentazione rimane attuale invece di accumularsi come un sedimento?

Questi dati sono più difficili da ricavare da un'API. Richiedono di pensare a quali risultati vuole effettivamente dai suoi team, il che, è vero, è il lavoro più difficile. Ma sono le domande che contano, perché riguardano i risultati piuttosto che gli input.

La spesa in gettoni indica la quantità di calcolo acquistata. Se quel calcolo è diventato qualcosa di utile è una questione completamente separata. Le aziende che non mantengono questa distinzione costruiranno dashboard molto costosi che non mostreranno quasi nulla.

Abbiamo passato anni a ottimizzare la metrica sbagliata per la produttività degli sviluppatori. Abbiamo forse un trimestre prima che lo stesso errore venga inserito in tutti i rapporti sull'adozione dell'AI nelle aziende. La finestra per evitarlo è aperta, ma non rimarrà tale.

L'AI Divide divide il suo team a metà

2026-04-10T00:00:00Z

La settimana scorsa ho partecipato a una telefonata con un mio amico che mi ha parlato di uno dei suoi clienti, un'azienda di logistica. Un caposquadra ha avuto una riunione di pianificazione in cui due dei suoi collaboratori avevano costruito un intero modello di scenario utilizzando l'AI prima ancora che la riunione iniziasse. Previsioni, ripartizione dei rischi, tre approcci alternativi. Le altre quattro persone del team si sono presentate con lo stesso formato di slide deck che usavano da due anni. Stessa struttura, stesso processo manuale, stesse stime temporali.

L'incontro è andato rapidamente a rotoli. La coppia assistita dall'AI non riusciva a capire perché gli altri non avessero fatto una preparazione di base che "richiede cinque minuti adesso". Gli altri si sono sentiti in un'imboscata, come se le regole del gioco fossero cambiate e nessuno glielo avesse detto. Il caposquadra ha trascorso il resto della giornata a controllare i danni.

Questa storia non mi sorprende più. Ne sento versioni da mesi.

Il divario è misurabile ora

Non si tratta solo di vibrazioni. Il 2025 Work Trend Index di Microsoft, un sondaggio condotto su 31.000 lavoratori in 31 Paesi, ha rilevato che il 67% dei leader ha familiarità con gli agenti AI, rispetto ad appena il 40% dei dipendenti. I leader sono molto più propensi a vedere l'AI come un acceleratore di carriera (79% contro il 67% dei dipendenti), e stanno anche risparmiando più tempo. Quasi un terzo dei leader afferma che l'AI fa risparmiare loro più di un'ora al giorno.

Ma ecco la parte che mi ha davvero colpito: alla domanda su come vedono l'AI, il 52% degli intervistati ha risposto che la trattano come uno strumento basato sui comandi. Dagli un'istruzione e ottieni un risultato. Solo il 46% l'ha descritta come un partner di pensiero, qualcosa con cui si ha un rapporto di collaborazione.

Non è una differenza da poco. Si tratta di due relazioni fondamentalmente diverse con la stessa tecnologia. E questi due gruppi partecipano alle stesse riunioni, lavorano agli stessi progetti e presumibilmente si muovono nella stessa direzione.

Due velocità, un team

La conseguenza pratica è che i team operano a due velocità completamente diverse. Le persone che hanno integrato l'AI nel loro lavoro quotidiano non producono solo più velocemente. Pensano in modo diverso. Approcciano i problemi in modo diverso. Arrivano alle riunioni con un lavoro che prima richiedeva una settimana e che viene svolto in un pomeriggio.

E le persone che non hanno adottato l'Intelligenza Artificiale (o che l'hanno provata una volta, l'hanno trovata insoddisfacente e sono passate oltre) stanno facendo un lavoro davvero solido. Voglio essere chiaro su questo punto. Non è che non siano bravi nel loro lavoro. È che il limite massimo di ciò che è possibile è stato spostato e loro stanno lavorando sotto quello vecchio.

Uno studio di Harvard sull'AI generativa nei team ha rilevato qualcosa di notevole: un singolo individuo con l'AI supera un intero team che ne è privo. Ma un team in cui tutti utilizzano l'IA supera tutti. L'implicazione è brutale. L'adozione mista non offre una via di mezzo. Offre un attrito.

L'ho visto in prima persona durante un workshop che ho tenuto il mese scorso. I partecipanti che utilizzavano regolarmente l'IA terminavano gli esercizi nella metà del tempo, poi si sentivano frustrati nell'attesa del resto. I partecipanti che non usavano l'AI si sentivano affrettati e, onestamente, un po' umiliati. Nessuno aveva intenzione di ottenere questo risultato. È successo semplicemente perché il divario di velocità è così grande ora.

Il vantaggio competitivo di cui nessuno parla

Ecco dove diventa davvero consequenziale. L'indagine di McKinsey State of AI 2025 ha rilevato che l'88% delle organizzazioni sta utilizzando l'AI in almeno una funzione. Sembra fantastico, vero? Ma quasi due terzi sono ancora bloccati nelle fasi di sperimentazione e pilota. Solo circa un terzo ha iniziato a scalare l'AI in tutta l'azienda. E le aziende che hanno scalato, quelle che McKinsey chiama "high performer"? Rappresentano circa il 6% degli intervistati.

Quel 6% si sta distaccando da tutti gli altri a una velocità che credo la maggior parte delle persone sottovaluti.

Gli high performer hanno una probabilità tre volte maggiore di aver riprogettato radicalmente i loro flussi di lavoro intorno all'AI. Sono tre volte più propensi ad avere leader senior che sostengono attivamente l'uso dell'IA e ne fanno da modello. Tre quarti di loro stanno scalando o hanno già scalato l'AI nella loro organizzazione, rispetto a un terzo di tutti gli altri.

I dati di Microsoft raccontano una storia simile. Le aziende che chiamano "aziende di frontiera" (quelle che hanno un'implementazione dell'AI a livello di organizzazione e una maturità avanzata) riportano risultati drammaticamente diversi. Il 71% dei leader delle aziende di frontiera afferma che la propria azienda è fiorente, rispetto al 39% dei lavoratori a livello globale. Il 55% afferma di poter assumere più lavoro, rispetto al 25% a livello globale. E hanno meno paura che l'AI prenda il loro lavoro, non di più.

Il divario tra queste aziende e tutte le altre non si sta riducendo. Sta accelerando.

Si tratta di un problema di persone mascherato da problema tecnologico

La tentazione è di risolverlo con gli strumenti. Lancia Copilot, acquista alcune licenze, invia un'e-mail a tutta l'azienda sulle risorse AI. Fatto.

Ma la vera sfida è culturale. È il caposquadra in quella telefonata che cerca di tenere insieme un gruppo in cui metà delle persone si sente sovralimentata e l'altra metà si sente lasciata indietro. È il manager che deve spiegare a un veterano di 20 anni che il suo flusso di lavoro, quello che ha perfezionato per un decennio, potrebbe non essere più l'approccio migliore. È il dipendente junior che sta usando silenziosamente l'AI per produrre un lavoro di livello superiore e non sa se essere orgoglioso o preoccupato per le ricadute politiche.

Microsoft ha scoperto che il 47% dei leader elenca l'aggiornamento dei dipendenti esistenti come strategia principale per la forza lavoro. Questo è incoraggiante, credo. Ma l'upskilling funziona solo se le persone vogliono effettivamente imparare. E in questo momento, una parte significativa della forza lavoro ha deciso che l'AI non è rilevante per loro, non è affidabile o non vale lo sforzo. Alcuni di loro potrebbero avere ragione su strumenti specifici. Ma la traiettoria più ampia non è opzionale (lo dico da persona che è stata scettica nei confronti di molti cicli di hype tecnologico nel corso degli anni, e questo sembra diverso).

Dove si sta dirigendo

Non credo che il divario scompaia. Penso che si allarghi. Le persone che adottano l'AI continueranno a diventare più veloci, a produrre di più, ad alzare il livello di "produzione normale". Le persone che non lo fanno sentiranno una pressione crescente, sia da parte della direzione, sia da parte dei colleghi, o semplicemente dalla realtà ambientale che i loro colleghi stanno facendo cose che loro non possono fare.

Le aziende che riusciranno a capire come coinvolgere tutto il team, non solo gli appassionati, avranno un vantaggio reale. E questo vantaggio si moltiplica. Ogni mese di fluidità organizzativa dell'AI è un mese che i suoi concorrenti passano a discutere se acquistare o meno le licenze ChatGPT.

Il più grande vantaggio competitivo nell'era dell'AI non sarà il modello da utilizzare. Sarà il fatto che tutto il suo team lo utilizzi davvero.

Il team di logistica di cui ho parlato? Il mio amico mi ha detto che il caposquadra ha prenotato un workshop interno di due giorni. Non "ecco come fare un prompt". Piuttosto "ecco come questo cambia il modo di pianificare insieme". Gli scettici dovevano vedere ciò che era possibile nel contesto del loro lavoro, non in una demo generica con uno scenario inventato. E gli entusiasti dovevano imparare la pazienza. Per portare le persone con sé, invece di correre avanti.

Questo sembra essere il lavoro da fare in questo momento. Non solo adottare l'AI. Chiudere il divario. Prima che sia lei a chiudere voi.

Build vs Buy Reimagined: Cosa significa realmente nel 2026

2026-04-07T00:00:00Z

La scorsa settimana ho visto uno sviluppatore junior del nostro team creare un'applicazione CRUD funzionante, con autenticazione, migrazioni di database e un'interfaccia utente quasi decente, in circa 90 minuti. Con Copilot. Da zero.

Cinque anni fa, lo stesso compito avrebbe richiesto una settimana. Forse due, se si contano le operazioni di razionalizzazione delle configurazioni di distribuzione e dei flussi OAuth. E questo cambiamento, questa compressione del tempo di costruzione da giorni a ore, sta silenziosamente smantellando una delle domande più antiche del software: meglio costruire o comprare?

Il vecchio schema è morto

Per decenni, la questione "costruire o comprare" è stata un calcolo dei costi. Si stimava il numero di mesi-sviluppatore necessari per costruire una cosa, si moltiplicava per il salario caricato, si aggiungeva un po' di buffer per la manutenzione e si confrontava con il costo della licenza annuale di qualsiasi prodotto SaaS che facesse più o meno la stessa cosa. Se il SaaS era più economico, si comprava. Se i suoi requisiti erano abbastanza strani, ha costruito.

Questa strutturazione presupponeva che la costruzione fosse costosa. E lo era. Ma secondo i dati Octoverse 2025 di GitHub, lo sviluppo assistito dall'AI produce oggi un aumento del 20-30% del rendimento. L'80% dei nuovi sviluppatori su GitHub utilizza Copilot entro la prima settimana. Oltre 1,1 milioni di repository pubblici integrano già gli SDK di LLM. La costruzione è diventata drammaticamente più economica, quasi da un giorno all'altro.

Quindi la domanda non è più "costruire o comprare". È più simile a: per cosa si paga effettivamente quando si acquista un SaaS?

Il nuovo calcolo

Ecco ciò che penso che la maggior parte dei fondatori di SaaS (me compreso, onestamente) non voglia sentire: se la sua intera proposta di valore è "le abbiamo evitato di costruirla", è nei guai. Perché quel fossato è appena diventato molto meno profondo.

Quando un team può prototipare uno strumento interno funzionale in un giorno, l'asticella di ciò che giustifica un abbonamento mensile si alza notevolmente. Non deve solo essere migliore di quello che potrebbero costruire loro. Deve essere migliore di quello che potrebbero costruire con l'aiuto dell'AI.

Gartner ha previsto nell'aprile 2026 che entro il 2028, oltre la metà di tutte le aziende smetterà di pagare per l'intelligenza assistiva e favorirà le piattaforme che si impegnano a ottenere risultati dal flusso di lavoro. Ancora più grave: si prevede che entro il 2030, le aziende di software che sovrappongono l'AI alle applicazioni esistenti, anziché riprogettarle per l'esecuzione agenziale, subiranno una compressione dei margini fino all'80%.

Ottanta per cento. Non è un errore di arrotondamento.

Quindi cosa sopravvive davvero?

Ho riflettuto molto su questo aspetto, in parte perché stiamo costruendo Rasepi e devo essere onesto con me stesso su dove si colloca il nostro valore. E credo che la risposta si riduca a tre cose che sono davvero difficili da replicare con uno sprint di codifica nel fine settimana, a prescindere dalla bravura dell'assistente AI.

La profondità del dominio che non si può falsificare. Chiunque può costruire un editor di testo. Costruire un sistema di traduzione che tenga traccia delle modifiche del contenuto a livello di paragrafo, che rilevi le traduzioni obsolete attraverso l'hashing del contenuto e che gestisca l'adattamento strutturale tra le lingue? Questo richiede anni di conoscenza del dominio, incorporata nell'architettura. L'AI può aiutarla a scrivere il codice più velocemente, ma non può dirle cosa costruire.

**Il punto è che costruire è divertente. Mantenere? Non è affatto divertente. Gestire i casi limite nei sistemi di permessi multi-tenant, tenere il passo con le stranezze dei browser, gestire le migrazioni dei database tra le varie versioni, correggere i CVE alle 2 del mattino, gestire il bug dell'esportazione dei PDF che si presenta solo in Safari. L'AI rende più veloce la creazione iniziale, certo. Ma la ricerca di Forrester dell'aprile 2026 mostra che la maggior parte delle aziende non riesce ancora a trasformare l'adozione dell'AI in un impatto misurabile, in parte perché la parte difficile non è mai stata la scrittura del codice. Si tratta di mantenere l'oggetto in funzione, aggiornato e funzionante per anni. La costruzione è la parte facile. Sono i tempi di attività, i turni di reperibilità e le correzioni incrementali a costare.

Fiducia, sicurezza e privacy dei dati. Questo aspetto è sottovalutato. Quando costruisce qualcosa da solo, la sicurezza è di sua proprietà. È responsabile della crittografia a riposo, della registrazione degli audit, dei test di penetrazione, della conformità GDPR, SOC 2 e della prossima normativa di cui nessuno ha ancora sentito parlare. Un buon fornitore SaaS ha un intero team il cui unico compito è quello di assicurarsi che i suoi dati non finiscano in un posto dove non dovrebbero essere. Per la maggior parte delle aziende, questo non è un costo che vogliono sostenere internamente. E onestamente, la maggior parte degli strumenti interni che ho visto non dispone nemmeno di controlli di accesso adeguati, per non parlare di una traccia di audit di sicurezza.

La via di mezzo compostabile

L'aspetto interessante è che sempre più spesso la risposta non è "costruire" o "comprare". Si tratta di comporre. Scelga gli strumenti SaaS che fanno bene le cose difficili, espongono buone API e le permettono di costruire intorno a loro.

Questo è il motivo per cui le architetture di plugin sono così importanti in questo momento (e sì, questo è esattamente ciò in cui abbiamo investito con il sistema di plugin di Rasepi). I prodotti SaaS che prospereranno sono quelli che dicono: "Noi ci occupiamo del nucleo duro e specifico del dominio. Lei personalizza tutto il resto". Non "Ecco il nostro monolite, prendere o lasciare".

Il rapporto di Forrester dell'aprile 2026 ha rilevato che la maggior parte delle aziende sta ancora lottando per trasformare l'adozione dell'AI in un impatto aziendale misurabile. I grandi adottatori hanno il 47% di probabilità in più di collaborare con partner di consulenza per preparare i loro dati e sistemi. Il messaggio è chiaro: la capacità di costruzione grezza non è il collo di bottiglia. Sapere cosa costruire e avere l'infrastruttura per supportarlo è il vero vincolo.

Cosa significa per SaaS

Se gestisce un'azienda SaaS nel 2026, credo che ci siano alcune verità scomode:

Il risparmio di tempo era la classica vendita SaaS. Ma quando l'AI comprime il tempo di costruzione del 20-30%, il numero di "tempo risparmiato" nel suo foglio di calcolo del ROI si riduce proporzionalmente. Ha bisogno di una storia diversa.
Le caratteristiche sono la posta in gioco, i risultati sono il prodotto.** A nessuno interessa che lei abbia 47 integrazioni. A loro interessa che la documentazione sia aggiornata, che le traduzioni siano accurate, che il team utilizzi effettivamente lo strumento. Il linguaggio di Gartner sul "flusso di lavoro incentrato sui risultati" non è solo un gergo da analista. È la direzione che sta prendendo il mercato.
L'istinto di chiudere la piattaforma e di rendere difficile il passaggio è comprensibile. Ma Gartner ha esplicitamente avvertito che "i fornitori SaaS legacy che tentano di chiudere i sistemi di record rischiano di essere aggirati dai livelli di orchestrazione di cui le aziende si fidano di più". Ahi.

La versione onesta

Sarò schietto sulla mia posizione in merito. Costruire o comprare non ha mai riguardato la tecnologia. Si è sempre trattato di fiducia. Mi fido del fatto che questo fornitore comprenda il mio problema in modo così profondo che la sua soluzione sarà migliore di quella che potrei mettere insieme io?

Nel 2026, il "cobble together" è stato aggiornato in modo massiccio. Quindi anche la barra della fiducia si è alzata.

Per noi di Rasepi, questo significa che non possiamo essere solo uno strumento di documentazione che supporta le traduzioni. Dobbiamo essere così profondamente bravi nei problemi difficili, il monitoraggio delle traduzioni a livello di blocco, l'applicazione della freschezza dei contenuti, la complessità multi-tenant, che la costruzione di un sostituto sarebbe davvero dolorosa anche con i migliori strumenti di intelligenza artificiale del mondo.

Questo è il nuovo "build vs buy". Non "può costruirlo?", ma "deve spendere le sue energie per costruirlo quando qualcun altro ha già risolto le parti difficili?".

La domanda non ha mai riguardato il costo. Si trattava di capire dove si vuole spendere la propria attenzione. E in un mondo in cui la costruzione è economica, l'attenzione è l'unica risorsa scarsa rimasta.

Smetta di licenziare le persone perché esiste l'intelligenza artificiale

2026-04-04T00:00:00Z

Una mia amica gestisce i contenuti per un'azienda SaaS di medie dimensioni. L'anno scorso, il suo team era composto da otto persone. Scrittori, redattori, uno specialista di localizzazione, qualcuno che si occupava della base di conoscenze. Un buon team, una produzione solida. Poi l'amministratore delegato ha partecipato a una conferenza, è tornato entusiasta dell'AI e nel giro di tre mesi il team si è ridotto a tre persone. Il motivo? "Con gli strumenti dell'AI, tre persone possono produrre quello che prima facevano otto".

E tecnicamente, è vero. Le tre persone rimaste producono più o meno lo stesso volume. Post sul blog, documenti di aiuto, aggiornamenti sui prodotti, comunicazioni interne. I numeri sembrano buoni su un cruscotto.

Ma la mia amica non dorme bene da mesi. Sta passando dalla scrittura, all'editing, al prompt engineering, al QA dell'output dell'AI, alla gestione delle traduzioni e a tutto il lavoro strategico che un tempo era condiviso da tutto il team. I suoi due colleghi rimasti sono nella stessa barca. Uno di loro sta già cercando un altro lavoro.

L'azienda ha risparmiato cinque stipendi. Ma sta anche perdendo lentamente le tre persone che sanno effettivamente come funzionano le cose.

La matematica che sembra giusta ma non lo è

Ecco l'argomentazione che sta facendo il giro dei consigli di amministrazione da quando il ChatGPT si è diffuso: una persona con l'AI può ora fare il lavoro di dieci. E se è così, perché tenerne dieci?

È un argomento convincente. Semplice. Pulito. Si adatta a una diapositiva.

È anche pericolosamente incompleto.

Sì, l'AI può comprimere i compiti. Secondo il Work Trend Index 2024 di Microsoft, il 90% degli utenti dell'AI al lavoro afferma che gli strumenti li aiutano a risparmiare tempo. Gli utenti più assidui di Microsoft Teams hanno riassunto otto ore di riunioni utilizzando Copilot in un solo mese. Si tratta di un'intera giornata lavorativa recuperata solo dai riepiloghi delle riunioni. E l'85% afferma che l'AI li aiuta a concentrarsi sul lavoro più importante.

Questi sono numeri reali. I guadagni di produttività non sono immaginari.

Ma ecco ciò di cui la folla "licenzia nove persone" non parla mai: la persona che rimane non assorbe solo il risultato. Assorbe il carico cognitivo, il contesto, il processo decisionale, la coordinazione, la garanzia di qualità e tutte le conoscenze istituzionali che sono uscite dalla porta con quei nove ex colleghi.

Il carico mentale non è un foglio di calcolo.

Esiste un concetto in psicologia chiamato teoria del carico cognitivo. Descrive la quantità totale di sforzo mentale utilizzato nella memoria di lavoro in un dato momento. E ogni volta che si chiede a una persona di fare il pensiero che prima era condiviso da cinque persone, non si risparmia sforzo. Lo sta concentrando.

Ci penso spesso quando le persone mi dicono che l'AI rende i lavoratori "10 volte più produttivi". Produttivi in cosa? A produrre più parole? Spedire più biglietti? Generare più slide decks? Certo. Ma la parte più difficile del lavoro di conoscenza non è mai stata la produzione. È il pensiero. Decidere cosa produrre. Capire il contesto. Fare scelte di giudizio. Sapere quando una cosa è sbagliata, anche quando sembra giusta in superficie.

L'AI non fa questo per lei. L'AI le dà una prima bozza e lei deve essere abbastanza intelligente da valutarla, abbastanza esperto da cogliere gli errori più sottili e abbastanza presente da notare quando il risultato è sicuramente sbagliato. (Se ha mai visto qualcuno spedire un documento interno generato dall'AI senza leggerlo, sa esattamente cosa intendo).

Il rapporto State of the Global Workplace 2025 di Gallup ha rilevato che l'impegno globale dei dipendenti è sceso al 21% nel 2024, rispetto al 23% dell'anno precedente. Questo calo è costato all'economia mondiale una perdita di produttività stimata in 438 miliardi di dollari. L'impegno dei manager è calato ancora di più, dal 30% al 27%. Le donne manager hanno registrato un calo di sette punti. I manager sotto i 35 anni sono scesi di cinque punti.

Queste sono le persone che dovrebbero guidare l'adozione dell'AI. E si stanno esaurendo.

L'argomento dell'amplificazione

Permettetemi di offrire un modo diverso di pensare a questo problema.

Se una persona con AI può fare il lavoro di dieci, allora dieci persone con AI possono fare il lavoro di cento.

Lo legga di nuovo. Perché questa è la parte di cui quasi nessuno parla, ed è la parte che dovrebbe tenere ogni CEO sveglio la notte. Non perché faccia paura, ma perché è un'enorme opportunità che la maggior parte delle aziende sta buttando via.

Le aziende che licenziano metà della loro forza lavoro perché "l'AI può farcela" non sono efficienti. Sono miopi. Stanno ottimizzando per un numero di dipendenti trimestrale, mentre i loro concorrenti scoprono cosa succede quando si danno strumenti potenti a un team completo di persone motivate ed esperte.

L'ho visto in un evento per startup a Zurigo il mese scorso. Due aziende nello stesso spazio. Più o meno delle stesse dimensioni, stesso mercato. L'azienda A aveva ridotto il suo team di contenuti da dodici a quattro. L'azienda B aveva mantenuto tutti e dodici e aveva dato loro strumenti di AI e formazione. Indovini quale delle due stava producendo contenuti multilingue in sei lingue, eseguendo esperimenti con nuovi formati e inviando aggiornamenti settimanali dei prodotti alla loro base di conoscenze? (Non era l'azienda A).

Cosa succede in realtà quando si taglia

Vediamo cosa succede in pratica quando si sostituisce un team di dieci persone con uno o due super-lavoratori "potenziati dall'AI".

La prima settimana è fantastica. Le persone rimaste sono energizzate. Hanno nuovi strumenti. Producono molto. La leadership è entusiasta. I numeri del cruscotto sono incredibili rispetto all'organico.

**L'unica persona responsabile della documentazione scopre che i contenuti generati dall'AI hanno bisogno di una revisione seria. Non un editing leggero. Una revisione profonda. Perché l'AI non conosce le sfumature del suo prodotto, il contesto del suo cliente o le tre cose che ha cambiato la settimana scorsa e che hanno invalidato metà di ciò che è stato scritto. Il lavoro di revisione da solo si mangia il tempo che è stato "risparmiato" generando contenuti più velocemente.

Al quarto mese, emergono le lacune di conoscenza istituzionale. Ricorda le otto persone che ha lasciato andare? Non si limitavano a scrivere contenuti. Avevano rapporti con i product manager. Conoscevano i punti dolenti dei clienti grazie ad anni di modelli di ticket di assistenza. Sapevano quali argomenti della documentazione generavano il maggior numero di domande. Questa conoscenza non c'è più. L'intelligenza artificiale non ce l'ha di certo.

**Perché le persone rimaste sono sovraccariche, la qualità è diminuita e qualcuno ha finalmente notato che la base di conoscenze non viene aggiornata correttamente da settimane. Ma anche gli appaltatori non hanno un contesto, quindi lei paga di più all'ora per risultati peggiori.

Non me lo sto inventando. Ho visto questo schema ripetersi in tre diverse aziende solo nell'ultimo anno.

I dati dicono di mantenere le persone (e di formarle)

Il World Economic Forum's Future of Jobs Report 2025 ha chiesto a più di 1.000 datori di lavoro globali i loro piani per la forza lavoro. I numeri raccontano una storia interessante. Sì, il 40% dei datori di lavoro prevede di ridurre il personale quando l'AI automatizza i compiti. Ma l'85% prevede di migliorare la propria forza lavoro esistente. E il 70% prevede di assumere persone con nuove competenze, non meno persone.

Il rapporto prevede una crescita netta di 78 milioni di posti di lavoro entro il 2030. E questo dopo aver tenuto conto dei 92 milioni di ruoli sfollati. Il mondo non si sta muovendo verso un minor numero di lavoratori. Si sta spostando verso lavoratori diversamente qualificati.

Ed ecco il dato che dovrebbe far riflettere tutti gli Amministratori Delegati che "tagliano gli organici": Il 64% dei datori di lavoro ha identificato il sostegno alla salute e al benessere dei dipendenti come una strategia chiave per la disponibilità di talenti. Non "ridurre i costi". Non "automatizzare tutto". Sostenere il benessere. Perché le aziende che bruciano le loro persone non possono assumere quelle buone in seguito.

Nel frattempo, uno studio di BCG e Harvard Business School ha rilevato che quando i team hanno utilizzato l'AI per i compiti creativi, circa il 90% ha migliorato le proprie prestazioni, con un aumento della qualità dei risultati del 40% rispetto ai gruppi di controllo. Ma lo studio ha anche rilevato qualcosa che dovrebbe mettere a disagio ogni leader: la diversità delle idee tra i gruppi assistiti dall'AI è diminuita del 41%.

Pensi a cosa significa. Lei licenzia sette persone dal suo team di dieci persone. I tre che rimangono utilizzano l'AI per produrre lo stesso volume. Ma la gamma di idee, prospettive e approcci si riduce di quasi la metà. La sua produzione sembra produttiva, ma gradualmente diventa omogenea. E nessuno se ne accorge, fino a quando un concorrente non lancia qualcosa di veramente creativo e lei non riesce a capire perché il suo team non stia facendo lo stesso.

Il carico mentale che nessuno mette in preventivo

Il sondaggio di Microsoft ha rilevato che il 68% delle persone ha difficoltà a gestire il ritmo e il volume del lavoro, e il 46% si sente esaurito. E questo era lo stato delle cose prima che lei dicesse loro che ora stanno facendo il lavoro dei loro tre ex compagni di squadra.

Ecco qualcosa che non appare nei dashboard di produttività: il costo cognitivo di essere l'ultima linea di difesa. Quando è l'unica persona a rivedere i risultati dell'AI, non può avere una giornata no. Quando è l'unico proprietario della base di conoscenze, ogni domanda di assistenza arriva sulla sua scrivania. Quando non c'è nessuno con cui scambiare idee perché il team è stato "dimensionato correttamente", ogni decisione è solo sua.

Ho costruito Rasepi in parte perché ho visto questo problema da vicino. Quando i team di documentazione si riducono, la conoscenza non si riduce con loro. La quantità di contenuti che devono esistere, essere aggiornati ed essere accurati in tutte le lingue non diminuisce solo perché ci sono meno persone che li mantengono. Anzi, aumenta (tra l'altro, questo è esattamente il problema che stiamo risolvendo con Rasepi, grazie a funzioni come le date di scadenza forzate e le traduzioni a livello di blocco, che rendono i team più piccoli davvero più efficaci, anziché più sovraccarichi).

Ma anche i migliori strumenti non risolvono una decisione fondamentalmente sbagliata in materia di personale. Non si può automatizzare la necessità di giudizio umano, di contesto e di attenzione. Si può solo rendere questi esseri umani più efficaci.

Cosa fanno le aziende intelligenti

La cosa più impressionante dei dati di Microsoft è l'aspetto dei "power user dell'AI". Si tratta di persone che utilizzano l'AI più volte al giorno e risparmiano oltre 30 minuti. Hanno il 68% di probabilità in più di sperimentare diversi modi di utilizzare l'AI. Non si limitano a generare più risultati. Riprogettano il modo in cui avviene il lavoro.

Ed ecco la novità: esistono all'interno delle organizzazioni che investono in loro. I power user dell'AI hanno il 61% di probabilità in più di sentir parlare il loro CEO dell'importanza dell'AI sul lavoro. Hanno il 53% di probabilità in più di ricevere dalla leadership l'incoraggiamento a ripensare l'intera funzione. Ricevono una formazione personalizzata, non solo un accesso a ChatGPT.

In altre parole, i lavoratori AI più produttivi non sono i solitari sopravvissuti a un licenziamento. Sono membri di team sostenuti e investiti.

Permettetemi di fare un contrasto con ciò che vedo nelle aziende che hanno scelto la strada del "taglio del personale". I dipendenti rimasti non sono dei power user. Sono generalisti sopraffatti che cercano disperatamente di far funzionare le cose. Non hanno il tempo di sperimentare l'IA perché sono troppo impegnati a usarla per sopravvivere. Non c'è un ripensamento della funzione, perché la funzione è solo... loro, da soli, che fanno tutto.

Il problema della conoscenza di cui nessuno parla

C'è un'altra cosa. E non sento nessuno parlarne, il che è strano perché dovrebbe essere ovvio.

Quando si licenziano i lavoratori esperti della conoscenza, la conoscenza se ne va con loro. Non rimane nell'edificio. Non è nel wiki. Non è nell'AI. È nella testa delle persone che hanno costruito i processi, compreso i casi limite e saputo quali clienti erano interessati a quali dettagli.

Sa cosa succede quando si hanno grandi strumenti di AI e nessuna conoscenza istituzionale? Si ottengono informazioni ben formattate, fornite con sicurezza e completamente sbagliate. In scala.

Il mese scorso ho parlato con una responsabile della documentazione di un'azienda fintech (non ha voluto essere nominata, il che la dice lunga). Dopo che il loro team è stato ridotto da sei a due, hanno iniziato a fare molto affidamento sull'AI per la manutenzione dei documenti degli sviluppatori. Nel giro di quattro mesi, hanno notato un aumento dei ticket di assistenza. I documenti sembravano a posto. Erano ben scritti, aggiornati in superficie. Ma contenevano errori sottili che solo una persona con una profonda conoscenza del prodotto avrebbe colto. Una descrizione dei parametri API tecnicamente corretta, ma praticamente fuorviante. Una guida alla migrazione che mancava un passaggio che tutti i membri del vecchio team conoscevano. Piccole cose che l'AI non può sapere, perché non partecipa ai suoi standup, non legge i suoi thread su Slack, non sente il frustrato "Oh, quel documento è di nuovo sbagliato" del tecnico dell'assistenza alla macchinetta del caffè.

La vera domanda

Quindi, ecco su cosa penso che la conversazione dovrebbe vertere.

Non: "Quante persone possiamo tagliare ora che abbiamo l'AI?".

Ma: Cosa diventa possibile quando diamo l'IA a tutti quelli che abbiamo già?".

Il suo team di documentazione di dieci persone con strumenti di AI non diventa ridondante. Diventa un team in grado di gestire i contenuti in dodici lingue invece che in due. Che può mantenere aggiornato ogni contenuto con controlli di freschezza automatizzati. Può sperimentare nuovi formati, eseguire test A/B sui contenuti di aiuto, costruire guide interattive e avere ancora tempo per pensare strategicamente a ciò di cui i clienti hanno effettivamente bisogno.

Il suo team di marketing di dieci persone con l'AI non diventa cinque persone che fanno lo stesso lavoro con più stress. Diventa dieci persone che possono personalizzare le campagne su una scala che prima era impossibile, testare più varianti creative, rispondere più velocemente ai cambiamenti del mercato e avere ancora la larghezza di banda cognitiva per proporre idee veramente originali che l'AI non avrebbe mai generato.

Non si tratta di un costo. È un investimento con un ritorno che si moltiplica.

Dove si va a finire

Le aziende che vinceranno i prossimi cinque anni non saranno quelle che taglieranno più teste. Saranno quelle che hanno capito come rendere i loro team esistenti davvero più capaci.

La questione non è se una persona può fare il lavoro di dieci. La questione è cosa succede quando tutti e dieci possono fare il lavoro di cento.

Se lei è un leader che sta leggendo, le chiedo una cosa. Prima di approvare il prossimo ciclo di "ristrutturazione abilitata dall'AI", parli con le persone che sono rimaste dopo l'ultimo ciclo. Chieda loro come si stanno comportando. Chieda loro cosa hanno smesso di fare perché non c'è tempo. Chieda loro che cosa si sta perdendo per strada.

E poi immagina cosa potrebbero realizzare se, invece di portare il carico da soli, avessero un team completo e i migliori strumenti disponibili.

Non è una fantasia. Per le aziende disposte a investire nelle loro persone invece di sostituirle, questi sono i prossimi dodici mesi.

I lettori e gli scrittori hanno modalità mentali diverse. Perché ogni strumento offre loro la stessa interfaccia?

2026-04-03T00:00:00Z

Apra subito Confluence e trovi un documento da leggere. Cosa vede?

Una barra degli strumenti. Pulsanti di modifica. Caselle di commento. Collegamenti alla cronologia della pagina. Una barra laterale piena di navigazione che non le serve. Briciole di pane. Campi di metadati. Indicatori di autorizzazione. Un'intera interfaccia di authoring che ruota intorno al testo che è venuto a leggere.

Ora pensi a ciò che desidera effettivamente: la risposta ad una domanda, o le tre fasi successive di un processo, o una politica che deve consultare prima di una riunione tra dieci minuti.

Lei è venuto per consumare. L'interfaccia presuppone che lei sia venuto per creare.

Questa è l'impostazione predefinita in quasi tutte le piattaforme di documentazione. Confluence, Notion, SharePoint, GitBook, Nuclino, Slite. Tutte presentano lo stesso ambiente ai lettori e agli scrittori. La pagina è la pagina. Tutti hanno la stessa visione, con o senza alcuni pulsanti di autorizzazione.

Sembra normale, perché non abbiamo mai avuto altro. Ma è una decisione di design, non una legge di natura. Ed è quella sbagliata.

La lettura e la scrittura non sono lo stesso compito cognitivo

Non si tratta di una preferenza dell'interfaccia utente. Si tratta di una differenza fondamentale nel funzionamento del cervello.

Quando scrive, si trova in modalità generativa. Sta costruendo, organizzando, decidendo cosa includere e cosa tralasciare. Ha bisogno di strumenti: opzioni di formattazione, controlli della struttura, inserimento di media, campi di metadati, cronologia delle versioni, funzioni di collaborazione. L'interfaccia deve offrirle potere e flessibilità.

Quando legge, è in modalità ricettiva. Sta analizzando, filtrando, estraendo ciò che è rilevante e cercando di andare avanti. Ha bisogno di chiarezza: tipografia pulita, layout mirato, distrazioni minime. L'interfaccia deve essere fuori dagli schemi.

La psicologia cognitiva ha un quadro chiaro per questo. La Teoria del Carico Cognitivo, sviluppata da John Sweller alla fine degli anni '80, distingue tra carico intrinseco (la difficoltà del materiale stesso), carico germinale (lo sforzo di apprendimento e di integrazione) e carico estraneo (tutto ciò che l'ambiente aggiunge e non aiuta). Ogni barra degli strumenti, barra laterale e pulsante di modifica visibile al lettore è un carico estraneo. Non aiuta a capire il contenuto. Competono attivamente per l'attenzione.

La ricerca di Mayer e Moreno (2003) sull'apprendimento multimediale ha dimostrato che la riduzione degli elementi estranei migliora sia la comprensione che la conservazione. Il loro principio di coerenza è diretto: Un'interfaccia di documentazione che mostra ai lettori i controlli di creazione sta violando questo principio in ogni singolo caricamento di pagina.

**Il lettore non ha bisogno di vedere gli strumenti dell'autore. Mostrarli comunque non è neutrale. È attivamente dannoso per la comprensione.

Come le piattaforme attuali gestiscono questo aspetto (per lo più non lo fanno)

Esaminiamo ciò che esiste.

Confluence ha una modalità di lettura e una modalità di modifica, ma la modalità di lettura è ancora circondata dalla navigazione, dai metadati e dall'albero della pagina della piattaforma. La barra degli strumenti di modifica scompare quando non si sta modificando, ma la cornice mentale di "questa è una pagina wiki modificabile" non scompare mai del tutto. Ogni lettore vede il pulsante "Modifica". La pagina sussurra: potresti cambiare questo.

Notion è peggiore da questo punto di vista. La sua filosofia di design è che tutto è sempre modificabile. Clicchi su un punto qualsiasi e sta scrivendo. Questo è brillante per gli scrittori. È terribile per i lettori che vogliono semplicemente assorbire i contenuti senza l'ansia di modificare accidentalmente qualcosa. La stessa [galleria di modelli] di Notion (https://www.notion.com/templates) lo dimostra: ogni modello è un'area di lavoro, non una pubblicazione.

SharePoint tecnicamente supporta diversi layout di pagina per la visualizzazione e la modifica, ma l'esperienza complessiva è ancora quella di una intranet aziendale. I lettori hanno la sensazione di trovarsi all'interno di uno strumento aziendale, non di leggere un documento ottimizzato per la comprensione.

GitBook si avvicina di più a un'esperienza di lettura, con il suo output pulito in stile documentazione. Ma anche in questo caso, l'esperienza di lettura si basa sul presupposto che il lettore sia uno sviluppatore che consulta documenti tecnici. Non è stato progettato per il consumatore di conoscenze generali.

Nessuna di queste piattaforme tratta la lettura come un'attività fondamentalmente diversa dalla scrittura. La trattano come la scrittura con la barra degli strumenti nascosta.

Il costo di un'unica interfaccia

Non si tratta solo di un problema estetico. Ha conseguenze misurabili.

Il sovraccarico di informazioni riduce la comprensione

Uno studio pubblicato nel Journal of Consumer Research ha rilevato che il sovraccarico di informazioni porta a una minore qualità delle decisioni, con un effetto che aumenta con l'aumentare del rapporto tra informazioni irrilevanti e rilevanti. Una pagina di documentazione con controlli di authoring visibili, alberi di navigazione e campi di metadati aumenta questo rapporto per ogni lettore che non è lì per scrivere.

Il cambio di contesto ha un costo reale

Quando un segnale di interfaccia dice "puoi modificare questo", attiva un quadro cognitivo diverso da "leggi questo". La ricerca di Gloria Mark presso la UC Irvine sull'attenzione e il multitasking ha rilevato che ci vogliono in media 23 minuti e 15 secondi per ricentrarsi completamente dopo un cambio di contesto. Un lettore che prende momentaneamente in considerazione l'editing (anche per correggere un errore di battitura) è stato estromesso dalla modalità di lettura. Non è un'ipotesi. Chiunque abbia utilizzato Notion conosce l'esperienza di fare clic per selezionare il testo e di iniziare a digitare per sbaglio.

Lettori e scrittori hanno esigenze diverse rispetto allo stesso contenuto.

Uno scrittore ha bisogno di vedere la struttura, i marcatori di formattazione, i tipi di blocco, i metadati e i segnali di collaborazione. Ha bisogno di un macchinario completo.

Un lettore ha bisogno di vedere un testo pulito, una gerarchia chiara e il percorso più veloce per raggiungere le informazioni che sta cercando. Ha bisogno del contenuto, non del macchinario.

Servire entrambi dalla stessa interfaccia significa che nessuno dei due riceve un'esperienza ottimizzata per quello che sta facendo.

E poi c'è il terzo pubblico: L'INTELLIGENZA ARTIFICIALE

Qui le cose si complicano e le piattaforme esistenti sono completamente impreparate.

La documentazione nel 2026 ha tre consumatori distinti, non due:

Gli scrittori che creano e mantengono i contenuti.
Lettori che consumano i contenuti visivamente
Sistemi AI che recuperano, analizzano e sintetizzano i contenuti in modo programmatico.

Ognuno di questi pubblici ha bisogno di un'interfaccia fondamentalmente diversa per lo stesso contenuto sottostante.

Gli scrittori hanno bisogno di ricchi strumenti di editing, funzioni di collaborazione e controlli strutturali. I lettori hanno bisogno di una presentazione pulita e mirata, con una distrazione minima. L'intelligenza artificiale ha bisogno di un output strutturato, elaborabile con metadati espliciti: segnali di freschezza, etichette di classificazione, indirizzamento a livello di blocco e markup semantico pulito.

Come abbiamo discusso in Builders, Not Developers, gli intermediari AI sono già il consumatore dominante della documentazione per una quota crescente di lavoratori della conoscenza. Il sondaggio sugli sviluppatori 2024 di GitHub ha rilevato che il 97% degli sviluppatori aziendali ha utilizzato strumenti di codifica AI. Entro il 2026, l'84% degli sviluppatori utilizza regolarmente strumenti di IA, con il 41% di tutto il codice generato dall'IA.

A questi sistemi di AI non interessa la barra laterale o la barra degli strumenti. Hanno bisogno di dati puliti. E una piattaforma che confonde la vista del lettore con la vista dello scrittore, confonde anche la superficie consumabile dall'AI con la superficie autoriale umana. Si tratta di tre discrepanze in un'unica interfaccia.

Come Rasepi separa le esperienze

Rasepi si basa sul principio che la creazione di contenuti e il consumo di contenuti sono attività diverse che meritano interfacce diverse.

L'ambiente dello scrittore

Quando scrive in Rasepi, ottiene un ambiente di scrittura completo. Editing di testo ricco con TipTap, controlli a livello di blocco, indicatori di stato di traduzione, gestione delle scadenze, strumenti di collaborazione, visualizzazioni della struttura dei contenuti e tutto ciò di cui uno scrittore ha bisogno per creare e mantenere una documentazione di alta qualità.

Lo scrittore vede il macchinario perché ha bisogno del macchinario.

L'ambiente del lettore

Quando qualcuno consuma un documento Rasepi, vede un'esperienza di lettura pulita e mirata. Nessun chrome di editing. Nessuna barra degli strumenti. Nessun segnale "puoi modificare questo". Solo il contenuto, presentato in un layout ottimizzato per la comprensione e la scansione.

Il lettore non vede il pulsante di modifica perché non è qui per modificare. È qui per imparare qualcosa, seguire un processo o trovare una risposta. L'interfaccia rispetta questo intento.

La superficie AI

Per i consumatori di AI, Rasepi espone i contenuti attraverso API strutturate con metadati completi. Ogni blocco contiene il suo punteggio di freschezza, lo stato di traduzione, l'hash del contenuto e le etichette di classificazione. I sistemi di AI possono interrogare i contenuti a livello di blocco, filtrare in base alla freschezza, escludere il materiale stantio o in bozza e recuperare esattamente i dati strutturati di cui hanno bisogno.

Non è necessario raschiare una pagina wiki e sperare nel meglio. L'IA riceve un'interfaccia creata ad hoc, proprio come il lettore e lo scrittore.

Un livello di contenuto, tre interfacce

La cosa importante è che non stiamo mantenendo tre copie del contenuto. Non si tratta del problema delle cinque copie di imbarco di cui abbiamo parlato in [Smettere di mantenere cinque copie dello stesso documento] (/blog/stop-maintaining-five-copies-of-the-same-document/).

Si tratta di un unico livello di contenuti, memorizzati come blocchi strutturati, serviti attraverso tre diverse visualizzazioni ottimizzate per tre diversi tipi di pubblico.

Lo scrittore modifica i blocchi. Il lettore vede contenuti assemblati e stilizzati. L'AI interroga i dati strutturati con i metadati. Stessi blocchi. Stessa fonte di verità. Strato di presentazione diverso per ogni consumatore.

Questo è possibile solo grazie all'architettura a livello di blocco. Ogni pezzo di contenuto è un'unità indirizzabile individualmente con i propri metadati. Può presentare questi blocchi in modo diverso a seconda di chi li richiede:

Pubblico	Esigenze	Ottiene
Scrittore	Formattazione, struttura, collaborazione, metadati	Ambiente di creazione completo con controlli a livello di blocco
Lettore	Testo pulito, gerarchia chiara, scansione veloce	Vista di lettura focalizzata, nessun chrome di editing
AI	Dati strutturati, punteggi di freschezza, classificazione	API a livello di blocco con metadati completi

Perché questo è più importante di quanto sembri

Leggendo questo potrebbe pensare: "Si tratta solo di UI. Viste diverse della stessa cosa. Quanto può essere importante?".

Molto importante, a quanto pare.

Fiducia dei lettori

Le persone si fidano dei contenuti che sembrano pubblicati. Quando una pagina sembra un wiki che chiunque può modificare, i lettori la ignorano inconsciamente. Quando lo stesso contenuto è presentato in una visualizzazione pulita, di qualità editoriale, gode di maggiore autorità. Questo non è irrazionale. È un segnale che qualcuno ha preso sul serio la presentazione, il che implica che ha preso sul serio anche il contenuto.

Nielsen Norman Group ha studiato questo aspetto in modo approfondito. La loro ricerca sulla credibilità dei contenuti mostra che la qualità del design e la presentazione sono tra i segnali più forti su cui gli utenti fanno affidamento per valutare l'attendibilità dei contenuti. Una vista dell'editore disordinata mina attivamente la credibilità del contenuto che visualizza.

Produttività dello scrittore

Gli scrittori che lavorano in un ambiente di authoring dedicato non devono scambiare il contesto tra "sto leggendo o sto scrivendo?". Gli strumenti sono lì perché si suppone che ci siano, non perché l'interfaccia non è in grado di decidere chi la sta guardando.

Affidabilità dell'AI

Quando i sistemi di AI dispongono di una superficie appositamente costruita con metadati strutturati, possono prendere decisioni migliori su cosa recuperare e cosa escludere. Possono controllare i punteggi di freschezza prima di includere un blocco in una risposta. Possono rispettare le etichette di classificazione. Possono filtrare per lingua, stato o pubblico. Nulla di tutto ciò è possibile quando l'AI esegue lo scraping della stessa pagina HTML progettata per i lettori umani.

Il cambiamento del modello mentale

Il presupposto fondamentale della maggior parte delle piattaforme di documentazione è: La pagina è l'unità e tutti interagiscono con la pagina.

Il presupposto di Rasepi è diverso: Il blocco è l'unità, e un pubblico diverso interagisce con i blocchi attraverso superfici appositamente costruite.

Sembra una piccola distinzione architettonica. Non lo è. È la differenza tra uno strumento che mostra accidentalmente i contenuti ai sistemi di intelligenza artificiale e uno che li serve deliberatamente. Tra un ambiente di scrittura che si dà il caso sia leggibile e un'esperienza di lettura progettata da zero. Tra un'interfaccia sufficiente e tre ottime.

La documentazione non è più solo scritta e letta. Viene scritta, letta, interrogata, tradotta, valutata, classificata e servita ai sistemi di intelligenza artificiale su scala. Un'unica interfaccia non può essere ottimizzata per tutte queste cose, e pretendere che lo sia è il modo in cui ci siamo ritrovati con wiki che nessuno vuole leggere e assistenti AI che estraggono risposte da pagine che non sono mai state progettate per essere consumate dalla macchina.

I lettori e gli scrittori sono in modalità mentali diverse. L'AI è in una modalità completamente diversa. L'interfaccia dovrebbe rifletterlo.

Lo stato dei documenti nel 2026: cinque tendenze che definiranno la prossima era

2026-04-03T00:00:00Z

Ogni pochi mesi mi ritaglio una mattinata per leggere e basta. Non il codice Rasepi, non i problemi di GitHub. Blog di concorrenti, relazioni di settore, annunci di conferenze, sondaggi tra gli sviluppatori. Tutto ciò che è stato pubblicato nell'ultimo trimestre e che riguarda la documentazione, la gestione della conoscenza o i flussi di lavoro assistiti dall'intelligenza artificiale.

L'ho fatto la scorsa settimana e il quadro che è emerso è stato più nitido di quanto mi aspettassi. Non perché un singolo annuncio sia stato rivoluzionario, ma perché cinque tendenze distinte stanno convergendo e, quando le si mette in fila, si delinea un quadro molto chiaro di ciò che le piattaforme di documentazione dovranno fare nei prossimi due anni.

Ecco cosa ho scoperto.

1. L'intelligenza artificiale è il lettore principale. Non gli esseri umani.

GitBook ha pubblicato un numero impressionante nel suo rapporto sui dati dei documenti AI: La lettura della documentazione da parte dell'AI è aumentata di oltre il 500% nel 2025. Cinquecento per cento. Non è un errore di arrotondamento.

Nel frattempo, il sondaggio di Stack Overflow 2024 Developer Survey ha mostrato che il 61% degli sviluppatori trascorre più di 30 minuti al giorno alla ricerca di risposte. Ma le modalità di ricerca sono cambiate. Il sondaggio di GitHub ha rilevato che il 97% degli sviluppatori aziendali ha utilizzato strumenti di codifica AI. Entro il 2026, l'84% degli sviluppatori utilizzerà quotidianamente strumenti di AI, con il 41% del codice ora generato dall'AI. Queste persone non stanno navigando nella barra laterale del wiki. Chiedono a Claude o a Copilot, e l'AI legge i suoi documenti per loro conto.

L'implicazione è difficile da sopravvalutare. Il consumatore più frequente della sua documentazione non è più una persona con una scheda del browser aperta. È un modello linguistico che effettua chiamate di recupero. E questo modello non è in grado di guardare una pagina e pensare: "Questo sembra obsoleto".

GitBook ha individuato questo problema in anticipo e ha risposto con il rapporto State of Docs 2026 e con una spinta verso i formati leggibili dalla macchina. Ha anche distribuito skill.md, una convenzione per la strutturazione delle informazioni sui prodotti specifica per gli agenti AI. Google è andata oltre con il suo Gemini API Docs MCP, che collega gli agenti di codifica alla documentazione corrente tramite il Model Context Protocol. Il loro ragionamento era esplicito: gli agenti generano codice obsoleto perché i loro dati di addestramento hanno una data di scadenza. La correzione MCP ha portato il tasso di superamento della valutazione al 96,3%.

Quindi la prima tendenza è risolta. L'AI è il lettore principale. Le piattaforme che trattano questo aspetto come un vincolo di progettazione fondamentale, non come una funzione da aggiungere in seguito, avranno un vantaggio strutturale.

2. La freschezza e i metadati di fiducia stanno diventando obbligatori

Anthropic ha intervistato 81.000 utenti Claude nel dicembre 2025 e ha pubblicato i risultati nel marzo 2026. Si tratta del più grande studio qualitativo sugli utenti di AI mai condotto (159 Paesi, 70 lingue). La preoccupazione più citata? L'inaffidabilità. Il 27% degli intervistati l'ha indicata come la preoccupazione principale e il 79% di loro l'ha sperimentata in prima persona.

Questo numero dovrebbe tenere sveglio ogni team di documentazione.

Quando le risposte dell'AI sono inaffidabili, il problema non è sempre il modello. Spesso il modello riproduce fedelmente ciò che ha trovato in un documento obsoleto. Il modello non ha avuto un'allucinazione. I suoi documenti erano semplicemente sbagliati e nessuno li ha segnalati.

I dati di Stack Overflow lo confermano da un altro punto di vista: L'81% degli sviluppatori prevede che l'AI sarà maggiormente integrata nel modo in cui documentano il codice nel prossimo anno. Se l'81% dei suoi utenti fornisce documenti all'IA e il 27% degli utenti dell'IA afferma che l'inaffidabilità è il problema principale, si ha un problema di fiducia che nessuna quantità di ingegneria tempestiva può risolvere. La soluzione è alla fonte.

Ecco perché i metadati di freschezza sono importanti. Non i timestamp "ultima modifica" (questi indicano quando qualcuno ha toccato il file, non se il contenuto è ancora accurato). La vera freschezza: stato di revisione, salute dei link, allineamento delle traduzioni, segnali di lettura, rilevamento della deriva dei contenuti. Metadati che una macchina può leggere e utilizzare per decidere se un documento è sicuro da citare.

Continuo a tornare ad un semplice inquadramento. La sua documentazione ha bisogno di un punteggio di credito. Non un timestamp. Un punteggio di credito. (Abbiamo costruito esattamente questo con il [sistema di punteggio di freschezza] di Rasepi(/caratteristiche/freschezza), e onestamente, vedere i dati del settore mi rende ancora più convinto che sia la decisione giusta).

3. La traduzione sta passando da "progetto" a "pipeline".

A febbraio, DeepL ha pubblicato un articolo intitolato "Le 6 trasformazioni della traduzione che le aziende globali non possono permettersi di perdere". La loro argomentazione: la traduzione sta diventando una sfida operativa continua, non un progetto in serie da realizzare trimestralmente.

Questo corrisponde a tutto ciò che vedo.

Il vecchio modello era semplice. Scrivere in inglese. Quando dispone di un budget, assume un traduttore o si rivolge a un servizio. Riceve le traduzioni. Le carichi. Fatto fino alla prossima volta. Il problema è che la "prossima volta" arriva sempre più velocemente quando il suo prodotto viene spedito settimanalmente e i documenti vengono aggiornati costantemente. Quando la versione tedesca torna dalla revisione, la fonte inglese è già cambiata due volte.

Il [Customization Hub] di DeepL (https://www.deepl.com/customization-hub) offre ora glossari, regole di stile e impostazioni di formalità, il che è fantastico. Ma se questi strumenti vivono al di fuori della sua piattaforma di documentazione, lei gestisce una catena di strumenti di traduzione: editor, esportazione, traduzione, revisione, reimport, ripetizione. Ogni passaggio è una possibilità di deriva.

Notion non ha alcun supporto multilingue nativo. Confluence lo offre attraverso i plugin del mercato. GitBook ha aggiunto la traduzione automatica nell'agosto 2025, che è un passo, ma opera a livello di pagina.

Il vero cambiamento è dal livello di pagina al livello di blocco. Quando si tiene traccia delle traduzioni a livello di paragrafo, si ritraduce solo ciò che è effettivamente cambiato. Una modifica tipica tocca forse due paragrafi su quaranta. Si tratta del 94% di lavoro di traduzione in meno. (Questa è l'architettura di traduzione principale di Rasepi e, onestamente, la cosa di cui sono più orgoglioso del prodotto. Ma anche se ci mettiamo da parte, la direzione del settore è chiara: la traduzione continua, incrementale e incorporata è la direzione da seguire).

4. Gli agenti AI hanno bisogno di contenuti strutturati, non di pagine wiki.

Questo aspetto si è cristallizzato per me quando Notion ha annunciato Custom Agents a febbraio. 21.000 agenti costruiti durante l'accesso anticipato. Agenti che rispondono alle domande delle basi di conoscenza, instradano i compiti, compilano rapporti sullo stato. Solo la Rampa ha oltre 300 agenti.

Atlassian ha seguito una direzione simile. Rovo AI in Confluence estrae il contesto da tutte le applicazioni Atlassian e di terze parti per generare contenuti. La loro proposta: "Contenuti ricchi di contesto e di alta qualità, basati sul lavoro esistente del suo team".

E poi Anthropic ha lanciato team di agenti in Claude Code, dove più agenti AI si coordinano autonomamente su compiti complessi. Opus 4.6 ha ottenuto un punteggio del 76% nel benchmark MRCR a 8 aghi 1M (rispetto al 18,5% del modello precedente), il che significa che è in grado di recuperare informazioni sepolte in profondità in enormi serie di documenti senza perdere la traccia.

Tutte e tre le aziende stanno costruendo agenti che consumano documentazione. Nessuna di loro ha risolto il problema della qualità delle fonti.

La documentazione degli agenti personalizzati di Notion riconosce esplicitamente il prompt injection risk quando gli agenti leggono contenuti non attendibili. Rovo di Atlassian prende tutto ciò che trova in Confluence. Se quel contenuto è vecchio di tre mesi, Rovo non lo sa. Ci costruisce sopra comunque.

Affinché gli agenti funzionino in modo affidabile, hanno bisogno di più di pagine di testo. Hanno bisogno di contenuti strutturati con identificatori stabili, segnali di freschezza espliciti, metadati di classificazione chiari e la capacità di distinguere "questo è attuale e revisionato" da "questo esiste ma nessuno lo ha toccato in un anno". Le pagine Wiki non forniscono tutto questo. Lo fanno i contenuti strutturati a livello di blocco con metadati di fiducia.

5. L'open source e il self-hosting stanno tornando in auge

Quest'ultimo è più un'intuizione supportata da dati che un singolo annuncio.

GitBook open-sourced la propria documentazione pubblicata alla fine del 2024 e ha lanciato un fondo OSS. Il loro ragionamento: i progetti open source meritano strumenti di documentazione gratuiti e di alta qualità. Ma la mossa segnala anche qualcosa di più ampio.

Notion è solo cloud. Non esiste un'opzione self-hosted. Confluence Data Center esiste, ma richiede una licenza. Quando la sua piattaforma di documentazione contiene le sue conoscenze operative più sensibili (playbook sugli incidenti, procedure di conformità, decisioni sull'architettura), la domanda "chi controlla questi dati?" non è astratta.

Il post di Anthropic "Claude è uno spazio per pensare" di febbraio contiene un'argomentazione interessante sulla fiducia e sui modelli di business. La loro affermazione principale: gli incentivi pubblicitari sono incompatibili con un assistente AI veramente utile. Hanno scelto di rimanere senza pubblicità, in modo che gli utenti possano fidarsi dello strumento.

Penso che ci sia un parallelo per le piattaforme di documentazione. Se il suo sistema di documentazione è closed-source e solo cloud, non può verificare ciò che alimenta l'AI. Non può verificare i calcoli di freschezza. Non può assicurarsi che i suoi dati rimangano sotto il suo controllo. Per i team che stanno implementando assistenti AI in cima alla loro base di conoscenze (e sempre più spesso lo fanno tutti), la verificabilità è importante.

Non si tratta di una polemica sul fatto che l'open source sia moralmente superiore. I prodotti closed-source possono assolutamente essere affidabili. Ma quando si costruiscono flussi di lavoro basati sull'AI in cima alla propria documentazione interna, la possibilità di ispezionare e verificare il sistema è un vantaggio pratico. Per noi, la licenza MIT di Rasepi non è stata un ripensamento. Si è trattato di una decisione progettuale radicata nella stessa logica: l'infrastruttura di documentazione deve essere verificabile.

Cosa significano queste cinque tendenze insieme

Singolarmente, ognuna di queste tendenze è gestibile. L'intelligenza artificiale legge i suoi documenti? Ok, aggiunga dei metadati leggibili dalla macchina. La freschezza è importante? Bene, aggiunga delle date di revisione. La traduzione deve essere continua? Certo, integri DeepL. Gli agenti hanno bisogno di una struttura? Bene, migliori il suo modello di contenuti. La sovranità è importante? Ottimo, offra un'opzione self-hosted.

Ma nel loro insieme, descrivono una piattaforma che appare fondamentalmente diversa da quella che la maggior parte dei team utilizza oggi.

Il divario è architettonico. Non si tratta di cinque funzionalità da aggiungere. Sono cinque presupposti che devono essere integrati nelle fondamenta. Come vengono archiviati i contenuti (a livello di blocco, non di pagina). Come viene modellata la fiducia (punteggi di freschezza, non timestamp). Come funziona la traduzione (incrementale, incorporata, per paragrafo). Come gli agenti AI accedono ai contenuti (API strutturate con metadati, non scrapes di pagine). Come vengono controllati i dati (aperti, verificabili, auto-ostabili).

Nessuna piattaforma consolidata è stata progettata su tutti e cinque questi aspetti contemporaneamente. Alcune le stanno aggiungendo pezzo per pezzo. GitBook si sta muovendo più velocemente sul fronte della leggibilità AI. Notion sta costruendo un'infrastruttura di agenti. Atlassian ha una distribuzione aziendale.

Ma progettare per tutti e cinque fin dal primo giorno? Questo è il vantaggio di iniziare da zero quando il terreno si sposta.

Mi rendo conto di essere di parte. Abbiamo costruito Rasepi proprio perché abbiamo visto queste tendenze convergere e volevamo una piattaforma che le assumesse tutte fin dall'inizio. Traduzione a livello di blocco, scadenza forzata, punteggio di freschezza, contenuti strutturati pronti per l'AI, open source. È la tesi dell'intero progetto.

Ma anche se non esistessimo, credo che qualsiasi lettura onesta di ciò che è accaduto nel primo trimestre del 2026 punti nella stessa direzione. La documentazione sta diventando un'infrastruttura. E l'infrastruttura ha requisiti diversi dalle pagine wiki.

I team che lo capiranno per primi non avranno solo una documentazione migliore. Avranno agenti AI più affidabili, costi di traduzione più bassi, meno sorprese di conformità e basi di conoscenza che rimarranno effettivamente affidabili nel tempo.

Questo è lo stato dei documenti nel 2026. La questione non è se queste tendenze sono reali. Si tratta di capire se la sua piattaforma è stata progettata per loro.

Cinque tendenze. Una domanda architettonica: la sua piattaforma di documentazione è stata progettata per il 2026, o sta ancora servendo ipotesi del 2016?

Fonti: GitBook AI docs data report, GitBook State of Docs 2026, GitBook skill.md, Google Gemini API Docs MCP, Stack Overflow 2024 Developer Survey, GitHub 2024 developer survey, Index.dev developer productivity statistics, Anthropic "What 81,000 People Want from AI", Anthropic "Claude è uno spazio per pensare", Claude Opus 4.6, Notion Custom Agents, Atlassian Rovo in Confluence, DeepL "6 trasformazioni di traduzione", DeepL Customization Hub, GitBook open source documentation, GitBook auto-translate.

Costruttori, non sviluppatori: Come Claude ha cambiato il destinatario dei suoi documenti

2026-04-02T00:00:00Z

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.

All'interno del motore di traduzione: Glossari, regole di stile e ritraduzione intelligente

2026-03-31T00:00:00Z

Il nostro post precedente sull'architettura ha trattato i plugin, le action guard e il sistema di pipeline. Questo post approfondisce il motore di traduzione, la parte che credo renda Rasepi fondamentalmente diverso da ogni altra piattaforma di documentazione.

Non il marketing che parla di tradurre paragrafi anziché pagine. Il codice vero e proprio. Come i glossari vengono risolti per tenant, come le regole di stile di DeepL e le istruzioni personalizzate modellano ogni traduzione, come l'hashing dei contenuti guida il rilevamento degli stanti e come l'orchestratore decide quali blocchi ritradurre.

La pipeline di traduzione

Quando un utente salva un documento, il sistema non si limita a ritradurre tutto. Esegue una sequenza piuttosto specifica:

Analizza il JSON di TipTap in singoli blocchi.
Confronta gli hash dei contenuti per rilevare quali blocchi sono stati effettivamente modificati.
Per i blocchi modificati, risolvere il glossario dell'inquilino e l'elenco delle regole di stile per la coppia di lingue.
Applica le regole di stile, le istruzioni personalizzate e la formalità dalla configurazione del locatario.
Invia solo i blocchi modificati a DeepL
Aggiorna i blocchi di traduzione e sincronizza gli hash dei contenuti

Ogni fase è un servizio proprio con una propria interfaccia. Questo è importante perché ogni fase può essere sostituita da qualcos'altro, un diverso fornitore di traduzioni, un diverso algoritmo di hashing, una diversa fonte di glossario.

Risoluzione del glossario: in base all'inquilino, DeepL-sincronizzato

I glossari di DeepL hanno un vincolo che la maggior parte delle persone non conosce: **Non è possibile modificare un glossario DeepL. Qualsiasi modifica comporta la cancellazione del vecchio glossario e la creazione di uno nuovo.

Rasepi gestisce questo aspetto trattando il database come fonte di verità e i glossari DeepL come artefatti di runtime da buttare. L'entità TenantGlossary memorizza tutto a livello locale:

public class TenantGlossary : ITenantScoped
{
    public Guid Id { get; set; }
    public Guid TenantId { get; set; }
    public string Name { get; set; }
    public string SourceLanguage { get; set; }     // e.g. "en"
    public string TargetLanguage { get; set; }     // e.g. "de"
    public string? DeepLGlossaryId { get; set; }   // Runtime DeepL ID
    public DateTime? LastSyncedAt { get; set; }
    public bool IsDirty { get; set; } = true;      // Triggers re-sync
    public ICollection<TenantGlossaryEntry> Entries { get; set; }
}

Quando un utente aggiunge una voce di glossario, ad esempio la mappatura di "Sprint Review" in "Sprint-Überprüfung" per EN→DE, il record del database si aggiorna immediatamente e IsDirty viene impostato su true. Il glossario DeepL non viene ricreato subito. Viene ricreato pigramente, la prossima volta che una traduzione ne ha effettivamente bisogno.

Il flusso di sincronizzazione

Prima di ogni chiamata di traduzione, il sistema risolve il glossario:

public async Task<string?> GetOrSyncDeepLGlossaryIdAsync(
    string sourceLanguage, string targetLanguage,
    CancellationToken ct = default)
{
    var glossary = await _db.TenantGlossaries
        .Include(g => g.Entries)
        .FirstOrDefaultAsync(g =>
            g.SourceLanguage == sourceLanguage &&
            g.TargetLanguage == targetLanguage, ct);

    if (glossary is null || glossary.Entries.Count == 0)
        return null;

    if (!glossary.IsDirty && glossary.DeepLGlossaryId is not null)
        return glossary.DeepLGlossaryId;

    // Dirty - delete old, create new
    if (glossary.DeepLGlossaryId is not null)
        await _deepL.DeleteGlossaryAsync(glossary.DeepLGlossaryId);

    var entries = glossary.Entries
        .ToDictionary(e => e.SourceTerm, e => e.TargetTerm);

    var deepLGlossary = await _deepL.CreateGlossaryAsync(
        $"rasepi-{glossary.Id}",
        glossary.SourceLanguage,
        glossary.TargetLanguage,
        entries);

    glossary.DeepLGlossaryId = deepLGlossary.GlossaryId;
    glossary.IsDirty = false;
    glossary.LastSyncedAt = DateTime.UtcNow;
    await _db.SaveChangesAsync(ct);

    return glossary.DeepLGlossaryId;
}

Tre cose da notare qui:

Sincronizzazione pigra. Intercettiamo l'API DeepL solo quando è effettivamente necessaria una traduzione. La modifica in blocco delle voci del glossario non comporta decine di chiamate all'API.
**La query passa attraverso i filtri della query globale EF, quindi TenantGlossaries è automaticamente individuato. Le voci del glossario dell'inquilino A non si riversano mai nelle traduzioni dell'inquilino B.
Un glossario per coppia di lingue. DeepL lo impone comunque. Un glossario EN→DE, un glossario EN→FR e così via. La coppia (SourceLanguage, TargetLanguage) è unica per inquilino.

Voci del glossario

Le singole voci sono solo mappature di termini:

CODICEBLOCCO_2

L'API le offre un CRUD completo e l'importazione/esportazione di CSV per una gestione massiva:

POST   /admin/glossaries                       Create glossary
POST   /admin/glossaries/{id}/entries           Add term
PUT    /admin/glossaries/{id}/entries/{entryId}  Update term
DELETE /admin/glossaries/{id}/entries/{entryId}  Remove term
POST   /admin/glossaries/{id}/import            Import CSV
GET    /admin/glossaries/{id}/export            Export CSV
POST   /admin/glossaries/{id}/sync              Force DeepL sync

L'importazione CSV è utilissima per i team che migrano da sistemi di memoria di traduzione esistenti. Esporta i termini, li ripulisce, li importa in Rasepi e la successiva esecuzione della traduzione utilizza automaticamente il nuovo glossario.

Regole di stile, istruzioni personalizzate e formalità

I glossari gestiscono la terminologia. Ma la terminologia è solo la metà. Una traduzione può utilizzare tutte le parole giuste e tuttavia suonare male. Tono sbagliato, formato della data sbagliato, convenzioni di punteggiatura sbagliate.

La Style Rules API di DeepL (v3) risolve questo problema. Può creare elenchi di regole di stile riutilizzabili che combinano due tipi di controlli:

Regole configurate, convenzioni di formattazione predefinite per date, orari, punteggiatura, numeri e altro.
Istruzioni personalizzate, direttive di testo libero che modellano il tono, la formulazione e le convenzioni specifiche del dominio.

Rasepi crea e gestisce queste istruzioni per tenant, per lingua di destinazione. L'entità TenantStyleRuleList memorizza il DeepL style_id insieme alle regole configurate e alle istruzioni personalizzate del tenant:

public class TenantStyleRuleList : ITenantScoped
{
    public Guid Id { get; set; }
    public Guid TenantId { get; set; }
    public string Name { get; set; }
    public string TargetLanguage { get; set; }      // e.g. "de"
    public string? DeepLStyleId { get; set; }       // Runtime DeepL style_id
    public string ConfiguredRulesJson { get; set; }  // Serialized configured rules
    public bool IsDirty { get; set; } = true;
    public DateTime? LastSyncedAt { get; set; }
    public ICollection<TenantCustomInstruction> CustomInstructions { get; set; }
}

Creazione di elenchi di regole di stile

Quando un amministratore imposta le regole di traduzione per il tedesco, Rasepi chiama l'API v3 di DeepL per creare l'elenco di regole di stile. Ecco come si presenta:

public async Task<string> CreateOrSyncStyleRuleListAsync(
    TenantStyleRuleList ruleList, CancellationToken ct = default)
{
    if (!ruleList.IsDirty && ruleList.DeepLStyleId is not null)
        return ruleList.DeepLStyleId;

    // DeepL style rule lists are mutable - we can update in place
    if (ruleList.DeepLStyleId is not null)
    {
        // Replace configured rules on existing list
        await _httpClient.PutAsJsonAsync(
            $"v3/style_rules/{ruleList.DeepLStyleId}/configured_rules",
            JsonSerializer.Deserialize<JsonElement>(ruleList.ConfiguredRulesJson),
            ct);

        // Sync custom instructions
        await SyncCustomInstructionsAsync(ruleList, ct);

        ruleList.IsDirty = false;
        ruleList.LastSyncedAt = DateTime.UtcNow;
        return ruleList.DeepLStyleId;
    }

    // Create new style rule list
    var payload = new
    {
        name = $"rasepi-{ruleList.TenantId}-{ruleList.TargetLanguage}",
        language = ruleList.TargetLanguage,
        configured_rules = JsonSerializer.Deserialize<JsonElement>(
            ruleList.ConfiguredRulesJson),
        custom_instructions = ruleList.CustomInstructions.Select(ci => new
        {
            label = ci.Label,
            prompt = ci.Prompt,
            source_language = ci.SourceLanguage
        })
    };

    var response = await _httpClient.PostAsJsonAsync("v3/style_rules", payload, ct);
    var result = await response.Content.ReadFromJsonAsync<StyleRuleResponse>(ct);

    ruleList.DeepLStyleId = result.StyleId;
    ruleList.IsDirty = false;
    ruleList.LastSyncedAt = DateTime.UtcNow;
    await _db.SaveChangesAsync(ct);

    return ruleList.DeepLStyleId;
}

A differenza dei glossari, gli elenchi di regole di stile di DeepL sono mutabili. Può sostituire le regole configurate sul posto con PUT /v3/style_rules/{style_id}/configured_rules, e le istruzioni personalizzate possono essere aggiunte, aggiornate o eliminate individualmente. Molto più amichevole per il perfezionamento iterativo.

Come appaiono le regole configurate

Le regole configurate riguardano le convenzioni di formattazione che variano in base alla lingua o alle preferenze aziendali. Cose come:

{
  "dates_and_times": {
    "time_format": "use_24_hour_clock",
    "calendar_era": "use_bc_and_ad"
  },
  "punctuation": {
    "periods_in_academic_degrees": "do_not_use"
  },
  "numbers": {
    "decimal_separator": "use_comma"
  }
}

Sembrano banali, ma si sommano velocemente. Un documento tedesco che utilizza il formato orario AM/PM e i decimali separati da un periodo, viene letto come "tradotto dall'inglese" da un lettore tedesco. L'impostazione di use_24_hour_clock e use_comma per i separatori decimali in tutte le traduzioni in tedesco elimina immediatamente questo problema.

Istruzioni personalizzate: questa è la vera potenza

Le istruzioni personalizzate sono direttive di testo libero, fino a 200 per elenco di regole di stile, ciascuna di 300 caratteri. In pratica, lei dice a DeepL come modellare la traduzione in un linguaggio semplice:

public class TenantCustomInstruction
{
    public Guid Id { get; set; }
    public Guid StyleRuleListId { get; set; }
    public string Label { get; set; }              // e.g. "Tone instruction"
    public string Prompt { get; set; }             // e.g. "Use a friendly, diplomatic tone"
    public string? SourceLanguage { get; set; }    // Optional source lang filter
}

Esempi reali dai nostri inquilini:

"Use a friendly, diplomatic tone" per una startup che desidera documenti accessibili
"Always use 'Sie' form, never 'du'" per uno studio legale tedesco
"Translate 'deployment' as 'Bereitstellung', never 'Deployment'" per i termini che necessitano di una gestione dipendente dal contesto, al di là della semplice mappatura del glossario
"Use British English spelling (colour, organisation, licence)" per le aziende con sede nel Regno Unito che traducono tra varianti di inglese
CODEBLOCCO_30 per corrispondere alle convenzioni europee

Le istruzioni personalizzate sono davvero potenti per le convenzioni specifiche del dominio che non si adattano alle voci del glossario. Un glossario mappa un termine ad un altro. Un'istruzione personalizzata può dire: "Quando traduce i documenti API, usi l'umore imperativo invece della voce passiva". Si tratta di un tipo di controllo completamente diverso.

Formalità

Il parametro formality di DeepL (default, more, less, prefer_more, prefer_less) è ancora disponibile come controllo separato insieme alle regole di stile. Tedesco "du" contro "Sie", francese "tu" contro "vous", livelli di cortesia giapponese. Questi sono impostati per ogni lingua di inquilino tramite TenantLanguageConfig:

public class TenantLanguageConfig : ITenantScoped
{
    public string LanguageCode { get; set; }
    public string DisplayName { get; set; }
    public bool IsEnabled { get; set; }
    public TranslationTrigger Trigger { get; set; }
    public string? Formality { get; set; }         // "more", "less", "prefer_more", etc.
    public string? StyleRuleListId { get; set; }   // Links to TenantStyleRuleList
    public string? TranslationProvider { get; set; }
    public int SortOrder { get; set; }
    public bool IsDefault { get; set; }
}

Formalità, regole di stile e glossari si compongono. Una singola chiamata di traduzione può contenere tutte e tre le cose:

var glossaryId = await GetOrSyncDeepLGlossaryIdAsync(sourceLang, targetLang, ct);
var styleId = await GetOrSyncStyleRuleListAsync(targetLang, ct);
var formality = tenantLanguageConfig.Formality ?? "default";

// Build the v2/translate request payload
var payload = new
{
    text = new[] { blockContent },
    source_lang = NormalizeLanguageCode(sourceLang),
    target_lang = NormalizeLanguageCode(targetLang),
    glossary_id = glossaryId,
    style_id = styleId,
    formality = formality,
    preserve_formatting = true,
    context = surroundingContext,  // Adjacent blocks, not billed
    model_type = "quality_optimized"
};

Due cose da notare qui:

Il parametro context. Passiamo i blocchi adiacenti come contesto per migliorare la qualità della traduzione. DeepL lo utilizza per risolvere le ambiguità, ma non traduce né fattura per questo. Un paragrafo sulle "celle" si traduce in modo diverso quando il contesto circostante è un documento di biologia rispetto ad un manuale di foglio elettronico.
Selezione del modello. Qualsiasi richiesta con style_id o custom_instructions usa automaticamente il modello quality_optimized di DeepL. Questo è il livello di qualità più alto. Non è possibile combinarli con latency_optimized, e questo è un vincolo intenzionale di DeepL. La personalizzazione dello stile necessita del modello completo.

Perché questo è importante più di quanto si pensi

Immagini un'azienda che scrive documenti interni in tedesco con l'informale "du" che improvvisamente passa al formale "Sie" in una sezione tradotta. Nel migliore dei casi sembra incoerente, nel peggiore poco professionale. La formalità gestisce questo aspetto. Ma la formalità, da sola, non può catturare un documento che utilizza i timestamp AM/PM quando l'ufficio tedesco usa il formato 24 ore, o che mette il simbolo della valuta prima del numero invece che dopo.

Tutti questi elementi (regole di stile, istruzioni personalizzate, formalità, glossari) producono traduzioni che sembrano scritte da qualcuno del suo team. Non come se fossero prodotte da una macchina che non sa dell'esistenza della sua azienda.

Il livello di servizio DeepL

Tutte le comunicazioni di DeepL passano attraverso IDeepLService. Questo strato avvolge l'SDK ufficiale di DeepL .NET e gestisce le chiamate API v3 per le regole di stile:

public interface IDeepLService
{
    // Text translation (v2)
    Task<TextResult> TranslateTextAsync(
        string text, string sourceLanguage, string targetLanguage,
        string? options = null);

    Task<TextResult[]> TranslateTextBatchAsync(
        IEnumerable<string> texts, string sourceLanguage,
        string targetLanguage, string? options = null);

    // Glossary management (v2)
    Task<GlossaryInfo> CreateGlossaryAsync(
        string name, string sourceLang, string targetLang,
        Dictionary<string, string> entries);
    Task DeleteGlossaryAsync(string glossaryId);
    Task<GlossaryInfo> GetGlossaryAsync(string glossaryId);
    Task<GlossaryInfo[]> ListGlossariesAsync();
    Task<Dictionary<string, string>> GetGlossaryEntriesAsync(
        string glossaryId);

    // Style rules (v3)
    Task<StyleRuleResponse> CreateStyleRuleListAsync(
        string name, string language,
        JsonElement configuredRules,
        IEnumerable<CustomInstructionRequest> customInstructions);
    Task ReplaceConfiguredRulesAsync(
        string styleId, JsonElement configuredRules);
    Task<CustomInstructionResponse> AddCustomInstructionAsync(
        string styleId, string label, string prompt,
        string? sourceLanguage = null);
    Task DeleteCustomInstructionAsync(
        string styleId, string instructionId);
    Task DeleteStyleRuleListAsync(string styleId);

    // Usage tracking
    Task<Usage> GetUsageAsync();
    Task<Language[]> GetSourceLanguagesAsync();
    Task<Language[]> GetTargetLanguagesAsync();
}

L'implementazione gestisce la normalizzazione del codice linguistico. DeepL richiede EN-US o EN-GB invece di en nudo, e PT-PT o PT-BR invece di pt:

private static string NormalizeLanguageCode(string code)
    => code.ToLower() switch
    {
        "en" => "EN-US",
        "pt" => "PT-PT",
        _ => code.ToUpper()
    };

La traduzione batch utilizza un chunking di 50 elementi per rimanere entro i limiti dell'API di DeepL, massimizzando al contempo il throughput:

public async Task<TranslationBatchResult> TranslateBatchAsync(
    Dictionary<string, string> texts,
    string sourceLanguage, string targetLanguage)
{
    var translations = new Dictionary<string, string>();
    long totalChars = 0;

    foreach (var chunk in texts.Chunk(50))
    {
        var results = await _deepL.TranslateTextBatchAsync(
            chunk.Select(kv => kv.Value),
            sourceLanguage, targetLanguage);

        for (int i = 0; i < chunk.Length; i++)
        {
            translations[chunk[i].Key] = results[i].Text;
            totalChars += chunk[i].Value.Length;
        }
    }

    return new TranslationBatchResult
    {
        Translations = translations,
        BilledCharacters = totalChars
    };
}

Dato che inviamo solo blocchi di dati, non interi documenti, un tipico batch di traduzione per una singola modifica contiene 1-3 blocchi invece di 40+. Ecco da dove deriva la riduzione dei costi del 94%.

L'orchestratore di traduzione

Il TranslationOrchestrator decide cosa fare con ogni blocco quando il documento sorgente cambia. Esaminiamo l'albero delle decisioni:

public async Task OrchestrateTranslationAsync(
    Guid entryId, List<Guid> changedBlockIds,
    CancellationToken ct = default)
{
    var entry = await _db.Entries
        .FirstOrDefaultAsync(e => e.Id == entryId, ct);

    var translations = await _db.EntryTranslations
        .Where(t => t.EntryId == entryId)
        .ToListAsync(ct);

    foreach (var translation in translations)
    {
        var langConfig = await GetLanguageConfigAsync(
            translation.Language, ct);

        var translationBlocks = await _db.TranslationBlocks
            .Where(tb => changedBlockIds.Contains(tb.SourceBlockId)
                      && tb.Language == translation.Language)
            .ToListAsync(ct);

        foreach (var block in translationBlocks)
        {
            if (block.IsLocked || block.TranslatedById is not null)
            {
                // Human-edited or locked - mark stale, don't overwrite
                block.Status = TranslationStatus.Stale;
            }
            else if (langConfig.Trigger == TranslationTrigger.AlwaysTranslate)
            {
                // Machine-translated, auto mode - retranslate now
                await RetranslateBlockAsync(block, translation.Language, ct);
            }
            else
            {
                // TranslateOnFirstVisit - mark stale, translate later
                block.Status = TranslationStatus.Stale;
            }
        }
    }

    await _db.SaveChangesAsync(ct);
}

Il punto chiave: **Se un traduttore ha modificato manualmente un blocco, magari aggiungendo un contesto culturale o riformulando per chiarezza, il sistema rispetta il suo lavoro. Contrassegna il blocco come obsoleto, in modo che il traduttore sappia che la fonte è cambiata, ma non sostituisce silenziosamente le sue modifiche.

I blocchi tradotti a macchina con AlwaysTranslate abilitato vengono ritradotti immediatamente. I blocchi tradotti a macchina con TranslateOnFirstVisit sono contrassegnati come stantii e tradotti quando qualcuno apre effettivamente il documento in quella lingua.

Inneschi di traduzione: quando avvengono le traduzioni

Ogni lingua ha un TranslationTrigger che controlla la tempistica:

public enum TranslationTrigger
{
    AlwaysTranslate,         // Translate on every save
    TranslateOnFirstVisit    // Translate when first opened in that language
}

Il AlwaysTranslate è utile per le lingue ad alta priorità, dove vuole che le traduzioni siano immediatamente attuali. Francese per un'azienda con una grande sede a Parigi. Tedesco per un'azienda con sede a Monaco.

TranslateOnFirstVisit è utile per le lingue che sono occasionalmente necessarie ma che non valgono il costo API di mantenere sempre perfettamente aggiornate. Quando qualcuno apre il documento in quella lingua, i blocchi obsoleti vengono tradotti al volo.

Entrambe le modalità utilizzano la stessa risoluzione del glossario, le stesse impostazioni di formalità e lo stesso hashing dei contenuti. L'unica differenza è la tempistica.

Adattamento unico del contenuto e della struttura

È qui che l'architettura dà i suoi frutti, al di là della semplice traduzione.

Quando un traduttore tedesco aggiunge una sezione di conformità DSGVO che non esiste in inglese, la aggiunge come nuovo blocco nella versione tedesca. Quel blocco non ha SourceBlockId, è contrassegnato come contenuto unico. Il sistema non lo invia mai per la ritraduzione, perché non esiste una fonte da cui tradurre. Esiste solo in tedesco.

Quando un traduttore giapponese cambia un elenco puntato in un elenco numerato (una convenzione comune nella scrittura tecnica giapponese), il flag IsStructureAdapted del blocco lo conserva per i futuri cicli di ritraduzione:

var translation = new TranslationBlock
{
    SourceBlockId = sourceBlockId,
    Language = targetLanguage,
    BlockType = translatedBlockType,
    SourceBlockType = sourceBlock.BlockType,
    IsStructureAdapted = translatedBlockType != sourceBlock.BlockType,
    StructureAdaptationNotes = "Numbered list preferred in JP technical docs",
    SourceContentHash = sourceBlock.ContentHash,
    Status = TranslationStatus.UpToDate,
};

Il flag IsNoTranslate gestisce i contenuti che devono essere copiati alla lettera: blocchi di codice, URL, nomi di prodotti, notazioni matematiche. Il fornitore di traduzione li salta completamente.

Mettere tutto insieme

Vediamo il flusso completo. Un utente a Londra modifica un paragrafo nel documento sorgente inglese, e il suo ufficio di Monaco ha il tedesco impostato su AlwaysTranslate:

L'utente salva. TipTap invia JSON all'API.
Estrazione dei blocchi e rilevamento delle modifiche. CreateBlocksFromDocumentAsync analizza JSON, ricalcola gli hash dei contenuti e confronta gli hash vecchi e nuovi per identificare i blocchi effettivamente modificati.
**Trova il EntryTranslation tedesco, controlla il blocco tedesco. È tradotto a macchina, non bloccato, non modificato dall'uomo, quindi è idoneo per la ritraduzione.
Configurazione della traduzione caricata. ID del glossario risolto tramite GetOrSyncDeepLGlossaryIdAsync("en", "de"), regole di stile tramite GetOrSyncStyleRuleListAsync("de"), formalità impostata su "more" (formale "Sie"), blocchi adiacenti passati come contesto per la disambiguazione.
Chiamata a DeepL. Blocco singolo inviato con ID glossario, ID stile, formalità e contesto.
Aggiornamento del blocco. Contenuto tradotto memorizzato, SourceContentHash sincronizzato, stato impostato su UpToDate. Un blocco tradotto invece di 40+. I 39 blocchi rimanenti? Non sono stati toccati.

Nel frattempo, il suo ufficio di Tokyo ha il giapponese impostato su TranslateOnFirstVisit. La stessa modifica contrassegna il blocco di traduzione giapponese come Stale. Quando qualcuno a Tokyo apre il documento, i passaggi 5-9 avvengono al volo. Il loro adattamento alla struttura (elenco numerato) viene conservato. I loro blocchi unici rimangono esattamente dove sono.

Credo che il motore di traduzione sia la parte di Rasepi che offre il valore più visibile. Traduzioni che utilizzano la sua terminologia, seguono le sue convenzioni di formattazione, obbediscono alle sue istruzioni personalizzate, corrispondono al suo tono, rispettano il lavoro dei suoi traduttori e costano una frazione di quanto costerebbe una ritraduzione di un documento completo. L'architettura rende tutto questo automatico, e non si intromette quando l'uomo vuole intervenire.

Lo stesso motore di DeepL che alimenta le traduzioni scritte alimenta anche Talk to Docs, la nostra interfaccia di documentazione conversazionale, con DeepL Voice che gestisce l'interazione parlata. Stessi glossari, stesse regole di stile, stessa formalità, stessa coerenza. Che il suo team legga la documentazione o ci parli, la qualità del linguaggio è identica.

Esplora l'API di traduzione →

Parlare con i documenti è meglio che leggerli

2026-03-10T00:00:00Z

C'è un motivo per cui le persone dicono "parliamone" quando qualcosa è complesso.

Quando cerchiamo di capire una nuova idea, di risolvere un problema o di ricordare un processo sotto pressione, spesso la conversazione è più facile della lettura. Non perché la lettura sia negativa. La lettura è uno degli strumenti più potenti che l'uomo abbia mai sviluppato. Ma la lettura è un'abilità appresa che si sovrappone a qualcosa di molto più antico: il linguaggio.

Siamo parlatori molto prima di essere lettori.

Questo è più importante di quanto si pensi, soprattutto ora che la maggior parte della conoscenza del mondo vive all'interno di documenti, wiki, PDF e lunghe pagine interne che nessuno vuole aprire a meno che non sia assolutamente necessario.

La lettura si impara. La conversazione è nativa.

Gli esseri umani hanno parlato per molto tempo prima di scrivere qualcosa. I bambini imparano a capire il linguaggio parlato in modo naturale. La lettura richiede istruzioni esplicite, ripetizioni e anni di pratica.

Anche per gli adulti altamente alfabetizzati, la lettura è ancora un atto più deliberato rispetto all'ascolto o alla conversazione. Richiede concentrazione visiva, attenzione continua, memoria di lavoro e interpretazione della struttura sulla pagina. Si decodificano simboli, si analizzano frasi, si costruisce un contesto e si decide cosa è importante.

La conversazione funziona in modo diverso. Quando le informazioni vengono fornite in forma parlata e interattiva, il cervello vive un'esperienza diversa:

Si sente in sequenza, piuttosto che visivamente travolgente.
Fornisce feedback e chiarimenti immediati
Riduce la necessità di scansionare e filtrare grandi blocchi di testo.
Rispecchia il modo in cui le persone chiedono aiuto nella vita reale.

Quest'ultimo punto è molto importante. In condizioni di incertezza, la maggior parte delle persone non vuole istintivamente leggere 1.500 parole. Vogliono chiedere: "Cosa devo fare dopo?".

Parlare riduce l'attrito cognitivo

Un documento è statico. Contiene tutto in una volta.

Sembra utile, e spesso lo è. Ma crea anche attrito. Una pagina piena di titoli, richiami, link, note, esempi e casi limite costringe il lettore a decidere cosa ignorare. Questo è cognitivamente costoso.

Quando si parla con un sistema informativo, di solito si ha l'esperienza opposta: la rilevanza prima di tutto, i dettagli poi.

Si pone una domanda. Ottiene una risposta. Poi si fa un'altra domanda.

Questo modello di interazione riduce il carico mentale in alcuni modi importanti:

1. Restringe lo spazio del problema

Un documento completo presenta l'intero panorama. Una conversazione presenta il prossimo passo utile.

Quando qualcuno chiede: "Come faccio ad assumere un nuovo ingegnere?"_ di solito non vuole l'intero manuale immediatamente. Vuole un orientamento. La conversazione consente di iniziare in piccolo e di espandersi solo quando necessario.

2. Conserva la memoria di lavoro

La lettura richiede di tenere in mente più cose mentre cerca la parte pertinente. L'interazione orale o conversazionale esteriorizza questo sforzo. Il sistema fa una parte maggiore del filtraggio per lei.

3. Sembra socialmente familiare

Gli esseri umani sono profondamente adattati allo scambio avanti e indietro. Chiediamo. Qualcuno risponde. Noi perfezioniamo. Loro chiariscono. Questo ciclo è una delle forme più antiche di apprendimento che abbiamo.

Anche quando il "qualcuno" è un sistema, la struttura è ancora naturale.

La lettura non è passiva. È proprio questo il punto.

Uno dei motivi per cui parlare può sembrare più facile è che la lettura non è così facile come si pensa. I lettori esperti lo fanno sembrare senza sforzo, ma il processo è molto attivo.

Per leggere bene, bisogna:

identificare la struttura
dedurre l'importanza
risolvere l'ambiguità
tenere a mente il contesto
collegare una sezione all'altra
decidere quando sfogliare e quando rallentare

Questo è un vero lavoro cognitivo.

In molte situazioni, questo lavoro è utile. La lettura profonda aiuta con le sfumature, la precisione e la comprensione a lungo termine. Ma in altre situazioni, soprattutto quando una persona è stanca, stressata, sovraccarica o sta semplicemente cercando di districarsi, parlare è spesso l'opzione mentalmente più leggera.

Questo è particolarmente vero sul posto di lavoro, dove le persone di solito non si avvicinano alla documentazione in condizioni ideali. Lo sono:

a metà dell'attività
interrotto
cambiano contesto
cercano di risolvere qualcosa in fretta
spesso già leggermente frustrato

In questo stato, l'accesso conversativo alle informazioni può risultare nettamente migliore rispetto all'accesso alla pagina.

Parlare cambia il rapporto con le informazioni

Qui c'è anche una dimensione emotiva.

I documenti possono sembrare formali e distanti. Implicano: Questo può essere utile come materiale di riferimento, ma può anche creare esitazione.

La conversazione è permissiva. Può essere vago. Può chiedere male. Può ammettere la confusione. Può dire: "Non so bene cosa sto cercando, ma ho bisogno di informazioni sulle richieste di accesso".

Questo è importante perché spesso le persone evitano la documentazione non perché non amano le informazioni, ma perché non amano lo sforzo e l'incertezza di trovare la parte giusta.

Parlare riduce questa barriera.

Perché questo è importante ora

Per molto tempo, i documenti dovevano essere letti perché non c'erano alternative pratiche. La ricerca ha aiutato le persone a trovare le pagine, ma non ha cambiato il modello di interazione. Bisognava ancora aprire la pagina, scansionarla ed estrarre ciò che serviva.

Questo sta cambiando.

Man mano che le interfacce diventano più conversazionali, le persone si aspettano sempre più che le informazioni rispondano, anziché esistere. Vogliono chiedere ciò di cui hanno bisogno in un linguaggio semplice e ricevere qualcosa di adatto al momento.

Questo non rende la lettura obsoleta. Cambia il suo ruolo.

La lettura diventa il livello profondo. La conversazione diventa il livello di accesso.

I migliori sistemi supporteranno entrambi:

parlare quando ha bisogno di orientamento o velocità
leggere quando ha bisogno di profondità, di verifica o di un contesto completo

Il rischio di semplificare eccessivamente

C'è un'avvertenza importante: parlare con le informazioni è meglio solo se le risposte sono affidabili.

Se un'interfaccia conversazionale fornisce risposte parziali, fuorvianti o troppo sicure, l'esperienza diventa peggiore della lettura, perché elimina la capacità dell'utente di ispezionare direttamente il materiale di partenza.

Quindi il futuro non è "sostituire tutti i documenti con la voce". Il futuro è offrire alle persone un modo più umano di accedere ai documenti, senza perdere la profondità e la precisione che la conoscenza scritta offre.

Questo equilibrio è importante. La conversazione è più facile, ma i documenti mantengono la struttura durevole, i dettagli e la responsabilità di cui le organizzazioni hanno bisogno.

Un'interfaccia più umana per la conoscenza

Il punto più profondo è semplice: le persone non pensano naturalmente per pagine. Pensano per domande, storie, frammenti e dialoghi.

Noi chiediamo:

Che cosa significa?
Cosa devo fare prima?
Qual è la parte importante?
Può spiegarlo in modo diverso?
Cosa è cambiato?

Queste sono mosse di conversazione, non di lettura.

Quindi, quando parlare con le informazioni è mentalmente più facile che leggerle, non è un segno di pigrizia intellettuale. Di solito è un segno che l'interfaccia corrisponde al modo in cui il cervello preferisce affrontare l'incertezza.

La lettura rimane essenziale. Ma come punto di accesso alla conoscenza, la conversazione è spesso migliore perché è più vicina a ciò che siamo per natura.

Non siamo prima di tutto lettori. Siamo prima di tutto dei parlatori. I sistemi di conoscenza più intuitivi lo ricorderanno.

Piattaforme di documentazione costruite per un'altra epoca

2026-03-08T00:00:00Z

Confluence e Notion non sono prodotti scadenti. Questo deve essere detto chiaramente all'inizio.

Hanno avuto successo per buone ragioni. Confluence è diventato la casa predefinita per la documentazione interna in molte aziende, perché ha dato ai team un luogo centrale per scrivere, organizzare e condividere le conoscenze. Notion ha conquistato le persone con flessibilità, esperienze di scrittura più pulite e una superficie del prodotto più moderna.

Entrambe le piattaforme hanno risolto problemi reali nell'epoca per cui sono state costruite.

Il problema ora è che il mondo intorno a loro è cambiato più velocemente delle loro fondamenta.

Non siamo più in un mondo in cui la documentazione deve solo essere scritta, archiviata e ricercata. Siamo in un mondo in cui ci si aspetta che la documentazione sia sempre più:

leggibile dalla macchina
consapevole della freschezza
sicura per il recupero da parte dell'AI
sufficientemente strutturata per l'automazione
dinamico tra le varie lingue e i vari tipi di pubblico
continuamente affidabile, non solo disponibile

Questa è una barra diversa.

Sono stati costruiti per un modello di conoscenza precedente all'Intelligenza Artificiale.

Le piattaforme di documentazione tradizionali sono state progettate sulla base di un semplice presupposto: se la pagina esiste ed è ricercabile, il problema è per lo più risolto.

Questo era sufficiente quando l'utente principale era un essere umano che apriva un wiki, sfogliava la pagina e applicava un giudizio. In quel modello, il compito della piattaforma era quello di facilitare la scrittura e la navigazione.

L'intelligenza artificiale cambia la descrizione del lavoro.

Ora la piattaforma non si limita ad archiviare la conoscenza per le persone. Sta producendo materiale di partenza per i sistemi che recuperano, classificano, riassumono e rispondono automaticamente alle domande.

Ciò introduce nuovi requisiti che le architetture precedenti non consideravano prioritari:

Quali contenuti sono affidabili in questo momento?
Quali pagine sono obsolete ma ancora ricercabili?
Quali sezioni sono state modificate di recente?
Quale versione linguistica è attuale?
Quali contenuti sono in bozza, archiviati, specifici di una regione o a bassa affidabilità?
Quali documenti dovrebbero essere esclusi completamente dalle risposte dell'AI?

Una piattaforma che non è stata costruita intorno a queste domande deve adattarle a posteriori. Questo è sempre più difficile che progettare per loro fin dall'inizio.

La forza dell'eredità diventa un freno all'eredità

I prodotti consolidati hanno dei vantaggi: distribuzione, ecosistema, marchio, familiarità con i clienti, integrazioni e team che sanno come spedire. Ma questi stessi punti di forza possono rallentare il cambiamento strutturale.

Perché? Perché le piattaforme mature comportano degli impegni.

Hanno:

anni di decisioni accumulate sui prodotti
enormi basi installate con flussi di lavoro esistenti
aspettative di retrocompatibilità
plugin ed estensioni che dipendono dal vecchio comportamento
modelli di dati ottimizzati per i casi d'uso di ieri

Quando una piattaforma come Confluence o Notion vuole aggiungere una funzionalità veramente nuova, spesso deve adattarla al sistema esistente, piuttosto che utilizzarla.

Questa è la sfida dell'incumbency: non solo si costruisce il futuro, ma si trascina con sé il passato.

Aggiungere funzionalità di AI non significa diventare nativi di AI

Molte piattaforme consolidate stanno ora sovrapponendo l'AI. Riassunti. Assistenza alla scrittura. Miglioramenti nella ricerca. Interfacce Q&A. Confluence ha Atlassian Intelligence, Notion ha lanciato Notion AI, e GitBook ha aggiunto AI-powered search. Si tratta di funzionalità utili. Alcune sono buone.

Ma c'è una differenza significativa tra:

aggiungere funzionalità AI a un prodotto di documentazione
costruire un prodotto di documentazione la cui architettura di base presuppone il consumo di IA fin dal primo giorno.

Il primo approccio spesso porta a funzioni di assistenza ai margini. Il secondo cambia le fondamenta.

Una piattaforma di conoscenza nativa dell'AI pone domande di progettazione diverse fin dall'inizio:

come devono essere strutturati i documenti in modo che i sistemi possano ragionare su di essi in modo sicuro?
come deve essere rappresentata la fiducia?
quali metadati devono essere di prima classe, non opzionali?
in che modo i contenuti obsoleti dovrebbero degradare la loro visibilità?
come limitare le risposte quando le fonti sottostanti sono deboli?

Queste sono domande di architettura, non di funzionalità.

Le piattaforme fresche hanno un vantaggio temporaneo

Qui è dove le piattaforme più recenti possono vincere, almeno per un po'.

Una nuova piattaforma ha la libertà di progettare intorno ai vincoli di oggi, invece che alle abitudini di ieri. Non deve conservare un decennio di presupposti su cosa sia un documento o su come debba comportarsi un wiki. Può fare scelte diverse in anticipo:

trattare la freschezza come un concetto di prima classe
rendere visibile la fiducia nella fonte sia agli esseri umani che alle macchine
memorizzare metadati più ricchi sullo stato dei contenuti
integrare i flussi di lavoro multilingue nel modello principale, anziché aggiungerli in un secondo momento
decidere che la ricerca e il reperimento dell'intelligenza artificiale debbano essere classificati in base alla fiducia, non solo alla pertinenza

Che la libertà è importante.

Nella tecnologia, gli operatori storici sono spesso più forti nei periodi di stabilità. I nuovi operatori sono spesso più forti quando il modello stesso si sta spostando.

L'era dell'AI è uno di questi cambiamenti.

Perché questo è particolarmente difficile per Confluence

Confluence è potente, ma proviene da una visione del mondo più vecchia. È stato costruito intorno a spazi per i team, pagine, navigazione gerarchica e a un modello aziendale ricco di plugin. Queste scelte avevano senso. Hanno ancora senso per molte organizzazioni.

Ma significano anche che il prodotto è molto complesso. Le piattaforme aziendali raramente possono reinventarsi in modo pulito. Devono negoziare con la propria storia.

Questo rende la modernizzazione più lenta. Non è impossibile. Solo più lenta.

Quando i requisiti dell'era dell'Intelligenza Artificiale richiedono metadati più puliti, una modellazione della fiducia più esplicita o una governance dei contenuti più basata sulle opinioni, un sistema costruito per ottenere la massima flessibilità attraverso anni di estensioni può faticare a muoversi in modo coerente.

Perché questo è particolarmente complicato per Notion

Notion ha un problema diverso. Sembra più nuovo, più leggero e più flessibile. Ma la flessibilità può anche giocare a suo sfavore.

Il punto di forza di Notion è che quasi tutto può diventare una pagina, un database, una nota, un documento leggero o uno spazio collaborativo. Questa flessibilità è ottima per i team. Non lo è altrettanto quando si ha bisogno di forti garanzie sul significato del contenuto, sullo stato in cui si trova e sul fatto che debba essere utilizzato come fonte attendibile da un sistema di intelligenza artificiale.

Più una piattaforma è libera, più è difficile imporre una semantica affidabile in seguito.

I sistemi di AI prosperano grazie alla struttura, ai metadati espliciti e ai segnali di fiducia. Gli spazi di lavoro flessibili e generici spesso necessitano di molte interpretazioni prima che il loro contenuto sia sicuro per questo tipo di utilizzo.

Niente di tutto questo significa che siano condannati.

Sarebbe un'analisi pigra dire che Confluence e Notion non possono adattarsi. Certo che possono.

Hanno team intelligenti, risorse significative e forti incentivi. Invieranno più funzionalità di intelligenza artificiale. Miglioreranno il reperimento, l'assistenza all'autore, i sommari, la governance e i flussi di lavoro strutturati. Nel tempo, potrebbero colmare gran parte del divario.

Ma la tempistica è importante.

Quando si verifica un cambiamento di questo tipo, il vantaggio spesso appartiene a chi è disposto a ricostruire le ipotesi più velocemente. Le piattaforme più recenti possono muoversi con maggiore coerenza, perché non sono in fase di retrofitting. Questo dà loro una finestra.

Potrebbe non essere una finestra permanente. Ma è reale.

La prossima fase delle piattaforme di documentazione

La prossima generazione di strumenti di documentazione sarà probabilmente giudicata meno per la capacità di far scrivere pagine alle persone e più per la capacità di gestire la conoscenza come un sistema affidabile.

Ciò significa che i vincitori faranno probabilmente bene cinque cose:

Modelleranno la fiducia in modo esplicito.
Distingueranno le conoscenze attuali da quelle obsolete.
Gestiranno il recupero dell'intelligenza artificiale come una superficie del prodotto principale, non come un componente aggiuntivo.
Supporteranno la conoscenza multilingue e specifica del pubblico senza frammentazione.
Offriranno ai team un maggiore controllo su quali informazioni vengono visualizzate, a chi e in quali condizioni.

Si tratta di una categoria diversa dal classico wiki.

Perché i nuovi inizi sono importanti

Ci sono dei momenti nel software in cui un prodotto pulito ha un vantaggio non perché gli operatori storici sono incompetenti, ma perché la storia è costosa.

Questo è uno di quei momenti.

Una nuova piattaforma può decidere, fin dal primo giorno, che i documenti non sono solo pagine. Sono fonti attive per gli esseri umani, gli agenti, i sistemi di ricerca e gli assistenti AI. Questo presupposto cambia tutto a valle.

Confluence e Notion possono arrivarci. Ma il percorso è più lungo, perché devono trasformare sistemi ottimizzati per un'altra epoca.

Questa trasformazione richiede tempo. Nel frattempo, le piattaforme più recenti hanno lo spazio per definire come dovrebbe essere la moderna infrastruttura della conoscenza.

Il più grande vantaggio di una piattaforma nuova non è la novità. È la libertà dai vecchi presupposti, proprio nel momento in cui questi presupposti smettono di funzionare.

Questo è un pezzo di prospettiva. Le affermazioni sui prodotti concorrenti si basano sulla documentazione e sugli annunci dei prodotti disponibili al pubblico al marzo 2026. Nutriamo un sincero rispetto sia per Confluence che per Notion: sono prodotti eccellenti che servono bene a milioni di team.

All'interno dell'architettura Rasepi: Plugin, protezioni d'azione e pipeline

2026-03-06T00:00:00Z

La maggior parte delle piattaforme di documentazione parla di "estensibilità" come le compagnie aeree parlano di "spazio per le gambe". Tecnicamente presente, praticamente deludente. Volevo che l'architettura di Rasepi fosse veramente estensibile senza diventare imprevedibile, quindi abbiamo costruito tre sistemi interconnessi: plugins per le capacità, action guards per il controllo e pipelines per l'esecuzione deterministica.

Questo post illustra il funzionamento di ciascuno di essi nella nostra base di codice reale.

Il sistema di plugin: modulare per design

Ogni plugin in Rasepi implementa IPluginModule, un'unica interfaccia che dichiara che cos'è il plugin, di quali servizi ha bisogno e quali percorsi espone:

public interface IPluginModule
{
    PluginManifest Manifest { get; }
    void RegisterServices(IServiceCollection services);
    void MapRoutes(IEndpointRouteBuilder routes);
}

Il PluginManifest è un dato puro. Descrive il plugin senza eseguire nulla:

public sealed class PluginManifest
{
    public required string Id { get; init; }
    public required string Name { get; init; }
    public required string Version { get; init; }
    public string Description { get; init; }
    public string Category { get; init; }
    public IReadOnlyDictionary<string, string> UiContributions { get; init; }
    public bool HasSettings { get; init; }
    public bool HasEndpoints { get; init; }
    public IReadOnlyList<string> Dependencies { get; init; }
}

Notare UiContributions. Questo dizionario mappa i punti di estensione del frontend con i nomi dei componenti, in modo che il frontend Vue sappia quali componenti dell'interfaccia utente contribuisce a ciascun plugin (un pulsante della barra degli strumenti, un pannello della barra laterale, una pagina di impostazioni).

La registrazione è una riga per ogni plugin

All'avvio, registriamo i plugin attraverso un'API fluente:

var pluginRegistry = new PluginRegistry();

pluginRegistry
    .AddPlugin<WorkflowPluginModule>(builder.Services)
    .AddPlugin<RulesPluginModule>(builder.Services)
    .AddPlugin<RetentionPluginModule>(builder.Services)
    .AddPlugin<ClassificationPluginModule>(builder.Services);

Ogni chiamata istanzia il modulo, lo memorizza nel registro e chiama RegisterServices() per collegare le sue dipendenze. Dopo la creazione dell'applicazione, una singola riga mappa tutti i percorsi dei plugin:

app.MapPluginRoutes(pluginRegistry);

Sotto il cofano, ogni plugin riceve un gruppo di rotte con uno scope in /plugins/{pluginId}/, con l'autorizzazione applicata automaticamente.

Esempio reale: il plugin Workflow

Ecco come appare un plugin reale, il modulo Workflow & Approvals:

public sealed class WorkflowPluginModule : IPluginModule
{
    public const string PluginId = "workflow";

    public PluginManifest Manifest { get; } = new()
    {
        Id = PluginId,
        Name = "Workflow & Approvals",
        Version = "1.0.0",
        Description = "Adds approval workflows to entry publishing.",
        Category = "Workflow",
        HasSettings = true,
        HasEndpoints = true,
        UiContributions = new Dictionary<string, string>
        {
            ["entry.toolbar.publish"] = "WorkflowPublishButton",
            ["entry.sidebar.status"]  = "WorkflowStatusPanel",
            ["hub.admin.settings"]    = "WorkflowHubSettings",
        }
    };

    public void RegisterServices(IServiceCollection services)
    {
        services.AddScoped<IWorkflowService, WorkflowService>();
        services.AddScoped<IActionGuard, WorkflowPublishGuard>();
    }

    public void MapRoutes(IEndpointRouteBuilder routes)
    {
        WorkflowEndpoints.Map(routes);
    }
}

La piattaforma principale non fa mai riferimento a WorkflowService o WorkflowPublishGuard direttamente. Li scopre attraverso il contenitore DI. Questa è la chiave per azzerare l'accoppiamento. L'applicazione principale non tocca mai il codice dei plugin.

Guardie d'azione: il livello di controllo

I plugin aggiungono capacità. Le guardie d'azione decidono se questa capacità, o qualsiasi azione del nucleo, può procedere. Sono validatori sincroni che intercettano le operazioni prima dell'esecuzione.

L'interfaccia è volutamente minimale:

public interface IActionGuard
{
    string PluginId { get; }
    string? ActionName { get; }  // null means guard ALL actions

    Task<ActionGuardResult> EvaluateAsync(
        ActionGuardContext context,
        IServiceProvider services,
        CancellationToken ct = default);
}

Quando ActionName è null, la guardia viene eseguita per ogni azione. Quando è impostato su qualcosa come "Entry.Publish", intercetta solo quell'azione specifica.

I contratti di contesto e di risultato

Ogni guardia riceve un contesto tipizzato con il nome dell'azione, il tenant, l'utente, l'entità e un bagaglio di proprietà:

public sealed record ActionGuardContext(
    string ActionName,
    Guid TenantId,
    Guid UserId,
    Guid EntityId,
    IReadOnlyDictionary<string, object?> Properties)
{
    public T? Get<T>(string key) =>
        Properties.TryGetValue(key, out var v) && v is T typed
            ? typed : default;
}

E ogni guardia restituisce un risultato prevedibile: allow, deny o allow-with-modifications:

public sealed record ActionGuardResult
{
    public bool IsAllowed { get; init; }
    public string? ReasonCode { get; init; }
    public string? Message { get; init; }
    public IReadOnlyDictionary<string, object?>? Modifications { get; init; }

    public static ActionGuardResult Allow() =>
        new() { IsAllowed = true };

    public static ActionGuardResult Deny(
        string reasonCode, string message) =>
        new() { IsAllowed = false, ReasonCode = reasonCode, Message = message };
}

Il campo Modifications è importante. Un guardiano può approvare un'azione ma riscrivere parte del contenuto (ad esempio, redigere i segreti prima della pubblicazione).

Nomi canonici delle azioni

Definiamo tutte le azioni intercettabili come costanti di stringa, in modo che non ci siano ambiguità su ciò che un guardiano può indirizzare:

public static class ActionNames
{
    public static class Entry
    {
        public const string Create  = "Entry.Create";
        public const string Save    = "Entry.Save";
        public const string Publish = "Entry.Publish";
        public const string Delete  = "Entry.Delete";
        public const string Archive = "Entry.Archive";
        public const string Renew   = "Entry.Renew";
    }

    public static class Hub
    {
        public const string Create = "Hub.Create";
        public const string Delete = "Hub.Delete";
        public const string TransferOwnership = "Hub.TransferOwnership";
    }

    public static class Translation
    {
        public const string Create  = "Translation.Create";
        public const string Publish = "Translation.Publish";
    }
}

Esempio reale: bloccare la pubblicazione senza approvazione

Il plugin Workflow registra una guardia che intercetta Entry.Publish:

public sealed class WorkflowPublishGuard : IActionGuard
{
    public string PluginId => WorkflowPluginModule.PluginId;
    public string? ActionName => ActionNames.Entry.Publish;

    public async Task<ActionGuardResult> EvaluateAsync(
        ActionGuardContext context,
        IServiceProvider services,
        CancellationToken ct = default)
    {
        var db = services.GetRequiredService<RasepiDbContext>();
        var entry = await db.Entries
            .AsNoTracking()
            .FirstOrDefaultAsync(e => e.Id == context.EntityId, ct);

        if (entry is null)
            return ActionGuardResult.Allow();

        var workflowService = services.GetRequiredService<IWorkflowService>();
        var check = await workflowService
            .CheckPublishAllowedAsync(entry.Id, entry.HubId);

        if (check.IsAllowed)
            return ActionGuardResult.Allow();

        return ActionGuardResult.Deny(
            "workflow.approval_required",
            check.Message ?? "Approval required before publishing.");
    }
}

La piattaforma principale non sa nulla dei flussi di lavoro di approvazione. Chiama semplicemente Entry.Publish attraverso la pipeline e la guardia lo blocca se il flusso di lavoro non è stato completato.

La pipeline di azione: dove tutto converge

Il ActionPipeline è il percorso di esecuzione unico per tutte le operazioni protette. Risolve quali protezioni si applicano, le valuta e blocca o esegue l'azione.

public sealed class ActionPipeline : IActionPipeline
{
    public async Task<ActionPipelineResult> ExecuteAsync(
        string actionName,
        ActionGuardContext context,
        Func<Task> action,
        CancellationToken ct = default)
    {
        var result = await EvaluateAsync(actionName, context, ct);
        if (!result.IsAllowed) return result;

        await action();  // All guards passed — execute

        return result;   // Return modifications for caller
    }
}

Il metodo EvaluateAsync fa il lavoro pesante:

public async Task<ActionPipelineResult> EvaluateAsync(
    string actionName,
    ActionGuardContext context,
    CancellationToken ct = default)
{
    // 1. Which plugins are enabled for this tenant?
    var enabledPlugins = await _resolver.GetEnabledPluginIdsAsync();

    // 2. Which guards match this action?
    var applicable = _guards
        .Where(g => enabledPlugins.Contains(g.PluginId))
        .Where(g => g.ActionName == null || g.ActionName == actionName)
        .ToList();

    // 3. Evaluate each guard
    var denials = new List<ActionGuardResult>();
    var modifications = new List<ActionGuardResult>();

    foreach (var guard in applicable)
    {
        try
        {
            var guardResult = await guard.EvaluateAsync(context, _services, ct);
            if (!guardResult.IsAllowed)
                denials.Add(guardResult);
            else if (guardResult.Modifications?.Count > 0)
                modifications.Add(guardResult);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Guard threw. Treating as Allow.");
        }
    }

    // 4. Any denial blocks the whole action
    if (denials.Count > 0)
        return ActionPipelineResult.Blocked(denials);

    return modifications.Count > 0
        ? ActionPipelineResult.Allowed(modifications)
        : ActionPipelineResult.Allowed();
}

Qui ci sono tre importanti decisioni di progettazione:

Risoluzione per inquilino. Il TenantPluginResolver controlla quali plugin ogni inquilino ha installato e abilitato. Una protezione per un plugin disabilitato non viene mai eseguita.
Tutti devono passare. Se una guardia nega, l'azione viene bloccata. Si tratta di una posizione di sicurezza intenzionale.
**Se una guardia lancia un'eccezione, questa viene registrata e trattata come Allow(). Questo impedisce a un plugin non funzionante di bloccare l'intera piattaforma.

Risoluzione dei plugin per inquilino

Il resolver interroga la tabella TenantPluginInstallations (automaticamente ottimizzata per il tenant corrente dai filtri di interrogazione globale EF):

public sealed class TenantPluginResolver : ITenantPluginResolver
{
    public async Task<IReadOnlySet<string>> GetEnabledPluginIdsAsync(
        CancellationToken ct = default)
    {
        if (_cache is not null) return _cache;

        var ids = await _db.TenantPluginInstallations
            .Where(i => i.IsEnabled)
            .Select(i => i.PluginId)
            .ToListAsync(ct);

        _cache = ids.ToHashSet();
        return _cache;
    }
}

Effetti collaterali guidati dagli eventi

Le azioni sono sincrone. Gli effetti collaterali non lo sono. Dopo il completamento di un'azione, il servizio pubblica un evento di dominio:

await _eventPublisher.PublishAsync(
    EventNames.Entry.Created, entry.Id, new { entry.OriginalLanguage });

Gli eventi vengono inseriti in un canale in memoria ed elaborati da un EventConsumerWorker in background. Il worker instrada gli eventi a più sistemi:

Tracciamento dell'attività. Registra chi ha fatto cosa, quando
Fatturazione delle traduzioni.** Traccia i costi per fornitore
Gestori di eventi dei plugin. Qualsiasi plugin può sottoscrivere gli eventi del dominio

I gestori di eventi dei plugin implementano IPluginEventHandler:

public interface IPluginEventHandler
{
    string PluginId { get; }
    IReadOnlyList<string> SubscribedEvents { get; }

    Task HandleAsync(
        string eventName, Guid entityId,
        Guid? tenantId, Guid? userId,
        string payloadJson, IServiceProvider services,
        CancellationToken ct = default);
}

Il worker invoca solo i gestori il cui plugin è abilitato per il tenant. Ciò significa che gli effetti collaterali del plugin A non si disperdono mai in un inquilino che ha installato solo il plugin B.

Il motore di traduzione a livello di blocco

Questo è il punto in cui l'architettura dà i suoi frutti in modo più evidente.

Le piattaforme tradizionali traducono interi documenti. Noi traduciamo singoli blocchi: paragrafi, intestazioni, voci di elenco. Quando un utente modifica un paragrafo in un documento di 50 blocchi, solo quel paragrafo deve essere ritradotto. Questa è la fonte del nostro 94% di risparmio sui costi.

Come vengono creati i blocchi da TipTap JSON

Quando un utente salva un documento, l'editor TipTap invia JSON come questo:

{
  "type": "doc",
  "content": [
    {
      "type": "paragraph",
      "attrs": { "blockId": "a1b2c3d4-..." },
      "content": [{ "type": "text", "text": "Hello world" }]
    }
  ]
}

Il BlockTranslationService analizza questo JSON e crea singoli record EntryBlock:

public async Task<List<EntryBlock>> CreateBlocksFromDocumentAsync(
    Guid entryId, string language, string contentJson,
    int version, Guid userId)
{
    var doc = JsonDocument.Parse(contentJson);
    var content = doc.RootElement.GetProperty("content");

    int position = 0;
    foreach (var node in content.EnumerateArray())
    {
        var blockType = node.GetProperty("type").GetString();
        var blockJson = JsonSerializer.Serialize(node);

        // Strip metadata attrs before hashing
        var hashInput = StripBlockMetaAttrs(blockJson);

        var block = new EntryBlock
        {
            Id = ExtractOrGenerateBlockId(node),
            EntryId = entryId,
            Language = language,
            Position = position++,
            BlockType = blockType,
            ContentJson = blockJson,
            ContentHash = CalculateContentHash(hashInput),
            IsNoTranslate = ExtractNoTranslateFlag(node),
            Version = version,
        };

        _context.EntryBlocks.Add(block);
    }

    await _context.SaveChangesAsync();
    return blocks;
}

Hashing SHA256 per il rilevamento delle stalle

L'hash del contenuto è il cuore del rilevamento delle stalle. Eseguiamo l'hash del contenuto del blocco (dopo aver eliminato gli attributi dei metadati come blockId e deleted) utilizzando SHA256:

private string CalculateContentHash(string content)
{
    using var sha256 = SHA256.Create();
    var hashBytes = sha256.ComputeHash(Encoding.UTF8.GetBytes(content));
    return Convert.ToHexString(hashBytes);
}

Quando un blocco sorgente cambia, il suo hash cambia. Il sistema confronta quindi il SourceContentHash di ogni blocco di traduzione con l'hash corrente della sorgente, e le discrepanze vengono contrassegnate con Stale:

public async Task MarkTranslationsAsStaleAsync(List<Guid> changedBlockIds)
{
    var affected = await _context.TranslationBlocks
        .Where(t => changedBlockIds.Contains(t.SourceBlockId))
        .ToListAsync();

    foreach (var translation in affected)
    {
        translation.Status = TranslationStatus.Stale;
        translation.UpdatedAt = DateTime.UtcNow;
    }

    await _context.SaveChangesAsync();
}

Adattamento della struttura

I traduttori possono cambiare i tipi di blocco tra le varie lingue. Un elenco puntato inglese potrebbe diventare un elenco numerato tedesco, una preferenza culturale. Il sistema ne tiene traccia:

var translation = new TranslationBlock
{
    SourceBlockId = sourceBlockId,
    Language = targetLanguage,
    BlockType = translatedBlockType,
    SourceBlockType = sourceBlock.BlockType,
    IsStructureAdapted = translatedBlockType != sourceBlock.BlockType,
    SourceContentHash = sourceBlock.ContentHash,
    Status = TranslationStatus.UpToDate,
};

Fornitori di traduzione come plugin

I servizi di traduzione esterni (DeepL, Google Translate, ecc.) si collegano tramite ITranslationProviderPlugin:

public interface ITranslationProviderPlugin : IRasepiPlugin
{
    string[] GetSupportedLanguages();

    Task<string> TranslateAsync(
        string text, string sourceLanguage, string targetLanguage);

    Task<TranslationBatchResult> TranslateBatchAsync(
        Dictionary<string, string> texts,
        string sourceLanguage, string targetLanguage);
}

Il metodo batch riceve un dizionario di ID di blocchi da contenere, li traduce tutti e restituisce le traduzioni con un conteggio di caratteri. Dato che inviamo solo i blocchi non completi, e non l'intero documento, i costi rimangono minimi.

Isolamento degli inquilini: la rete di sicurezza invisibile

Tutti i sistemi sopra descritti funzionano all'interno di un rigoroso isolamento degli inquilini.

Il TenantContextMiddleware risolve l'inquilino dal JWT su ogni richiesta e verifica l'appartenenza:

public async Task InvokeAsync(
    HttpContext context, TenantContext tenantContext, RasepiDbContext db)
{
    var tenantIdClaim = context.User.FindFirstValue("tenant_id");
    var userIdClaim = context.User.FindFirstValue(ClaimTypes.NameIdentifier);

    // Populate scoped context
    tenantContext.TenantId = Guid.Parse(tenantIdClaim);
    tenantContext.UserId = Guid.Parse(userIdClaim);

    // Verify membership — fail closed
    var membership = await db.TenantMemberships
        .Where(m => m.TenantId == tenantContext.TenantId
                  && m.UserId == tenantContext.UserId)
        .FirstOrDefaultAsync();

    if (membership == null)
    {
        context.Response.StatusCode = 401;
        return;  // No membership = no access
    }
}

I filtri globali delle query di Entity Framework assicurano che, anche se uno sviluppatore dimentica di filtrare per tenant, il livello del database lo faccia automaticamente:

modelBuilder.Entity<Hub>()
    .HasQueryFilter(h => h.TenantId == _tenantContext.TenantId);

Il risultato: db.Hubs.ToListAsync() restituisce sempre solo gli hub del tenant corrente. Le fughe di dati richiedono l'aggiramento attivo del filtro di query, che è vietato nella nostra base di codice.

Il quadro completo

Quando un utente fa clic su "Pubblica" su una voce, ecco cosa succede:

**L'autenticazione convalida il JWT, TenantContextMiddleware risolve e verifica l'inquilino.
Il controllore chiama la pipeline. IActionPipeline.ExecuteAsync("Entry.Publish", context, action)
La pipeline risolve le guardie. Interroga i plugin abilitati dall'inquilino e seleziona le guardie applicabili.
Le guardie valutano. La guardia del flusso di lavoro verifica le approvazioni, la guardia della conservazione verifica i criteri, la guardia delle regole convalida il contenuto. Tutti passano? La voce viene pubblicata.
Gli eventi si attivano. L'evento Entry.Published viene richiesto. Un lavoratore in background registra le attività, aggiorna la fatturazione delle traduzioni e chiama i gestori di eventi del plugin.
Verifica delle traduzioni dei blocchi. I blocchi obsoleti vengono identificati per essere ritradotti.

Ogni livello svolge il proprio lavoro. Nessun livello si inserisce in un altro. Questa è l'architettura.

Non abbiamo costruito questo perché l'estensibilità è di moda. L'abbiamo costruita perché una piattaforma di documentazione che non può adattarsi al flusso di lavoro di ogni team, alla fine sarà sostituita da una che può farlo. E una piattaforma che si adatta senza guardrail finirà per rompere qualcosa di importante.