Rasepi Blog

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.

Come funzionano effettivamente le traduzioni di Rasepi, e perché sembrano quelle del suo team

2026-03-31T00:00:00Z

Se ha mai eseguito un documento attraverso Google Translate, o onestamente qualsiasi strumento di traduzione, conosce il risultato. Tecnicamente corretto. Tonalmente sbagliato. Il suo prodotto viene improvvisamente chiamato in modo diverso. La stenografia interna del suo team scompare. Un "tu" formale dove la sua azienda usa l'informale, o il contrario.

L'output viene tradotto, ma non suona come lei.

È per questo che ho costruito il sistema di traduzione di Rasepi. Non "possiamo tradurre la documentazione" (ormai tutti gli strumenti possono farlo), ma "possiamo tradurla in modo che suoni effettivamente come se l'avesse scritta il nostro team".

La risposta è sì. E non richiede un team di traduttori professionisti per arrivarci.

Viene tradotto solo ciò che è stato modificato

La maggior parte delle piattaforme di documentazione traduce intere pagine. Se cambia una frase, l'intero documento viene ritradotto. Ogni lingua, ogni paragrafo, che sia cambiato o meno.

Rasepi funziona in modo diverso. Tiene traccia di ogni paragrafo individualmente. Quando modifica una sezione di un documento di 20 sezioni, solo quella sezione viene ritradotta. Le altre 19, in tutte le lingue, rimangono esattamente come erano.

Questo significa due cose:

**Stiamo parlando del 94% in meno per le modifiche tipiche. La maggior parte degli aggiornamenti riguarda una o due sezioni, non l'intera pagina.
**Se il suo team tedesco ha approvato una traduzione la settimana scorsa, la modifica di un paragrafo non correlato in inglese non influirà sul testo approvato.

Il sistema sa cosa è cambiato perché ogni paragrafo ha un'identità unica e un'impronta digitale del contenuto. Quando l'impronta digitale cambia, quel paragrafo specifico viene segnalato per una nuova traduzione. Nient'altro.

Il suo glossario, la sua terminologia

Ecco dove la cosa si fa interessante.

Ogni azienda ha il proprio vocabolario. "Sprint Review" potrebbe rimanere come "Sprint Review" nei documenti in tedesco, perché il team di Berlino usa il termine inglese. Oppure potrebbe diventare "Sprint-Überprüfung" perché il team di Monaco preferisce la versione tedesca. "Base di conoscenza" potrebbe essere "Wissensdatenbank" o "Knowledge Base" o qualcosa di completamente diverso coniato internamente dal suo team.

Rasepi le consente di creare un glossario per ogni lingua. In pratica, un elenco di termini e delle loro traduzioni approvate. Quando un paragrafo viene tradotto, il sistema controlla prima il suo glossario. Ogni termine del suo elenco viene tradotto esattamente nel modo in cui lei lo ha definito. Ogni volta. In ogni documento.

Può gestire il suo glossario direttamente in Rasepi:

Aggiungere termini uno per uno man mano che nota incongruenze
Importare un CSV** se dispone già di un elenco terminologico da un altro sistema.
Esportare il suo glossario** per condividerlo con traduttori esterni o altri strumenti.

Il glossario funziona per coppia di lingue. Il suo glossario inglese-tedesco è separato da quello inglese-francese. Questo è importante perché lo stesso termine inglese potrebbe richiedere un trattamento diverso nelle varie lingue. "Sprint Review" potrebbe rimanere inglese in tedesco ma essere tradotto in giapponese.

Quando aggiorna il glossario, la modifica ha effetto la volta successiva che un paragrafo viene tradotto in quella lingua. Non c'è bisogno di ritradurre tutto manualmente. Il successivo ciclo di editing naturale lo raccoglie.

Regole di stile: fare in modo che le traduzioni sembrino scritte da lei.

I glossari gestiscono le singole parole. Ma una traduzione può utilizzare tutti i termini giusti e sembrare comunque sbagliata. Tono sbagliato. Date nel formato sbagliato. Numeri con il separatore sbagliato. Simboli di valuta nel posto sbagliato.

Ecco a cosa servono le regole di stile.

Per ogni lingua, può impostare una serie di regole che controllano la forma delle traduzioni:

Convenzioni di formattazione

Questi sono i dettagli che fanno sembrare un documento nativo piuttosto che "ovviamente tradotto dall'inglese":

Formattazione della data e dell'ora. Orologio a 24 ore per il tedesco, AM/PM per l'inglese e altro ancora.
Formattazione dei numeri.** Virgola come separatore decimale in tedesco (3,14 invece di 3,14), punto per le migliaia
Regole di punteggiatura.** Formattazione del titolo accademico, stili delle virgolette e altre convenzioni regionali.

Scelga lei le convenzioni che corrispondono agli standard della sua azienda. Rasepi le applica a tutte le traduzioni in quella lingua, in tutti i documenti.

Istruzioni personalizzate

Qui le cose si fanno davvero potenti. Le istruzioni personalizzate sono direttive in linguaggio semplice che indicano al motore di traduzione come gestire il suo contenuto. Le scrive in frasi normali e il motore le segue.

Alcuni esempi:

"Utilizzi un tono amichevole e diplomatico " per un'azienda che desidera una documentazione accessibile.
"Utilizzi sempre la forma formale 'Sie', mai 'du'" per una comunicazione professionale in tedesco.
"Utilizzi l'ortografia inglese britannica: colore, organizzazione, licenza " quando il suo pubblico anglofono risiede nel Regno Unito.
"Inserisca i simboli di valuta dopo l'importo numerico " per adeguarsi alle convenzioni europee.
"Quando descrive gli endpoint API, utilizzi uno stato d'animo imperativo " per i documenti tecnici che devono essere diretti.

Può aggiungere fino a 200 istruzioni personalizzate per lingua. Esse lavorano insieme al suo glossario e alle regole di formattazione, e il motore di traduzione le considera tutte insieme in ogni traduzione.

Formalità

Il tedesco ha "du" e "Sie". Il francese ha "tu" e "vous". Il giapponese ha molteplici livelli di cortesia. Anche le lingue che non hanno pronomi formali/informali evidenti hanno differenze tonali importanti.

Rasepi le permette di impostare il livello di formalità per ogni lingua. Una volta configurato, ogni paragrafo tradotto corrisponde a quel tono. Se la sua azienda si rivolge ai lettori in modo formale in francese ("vous") ma informale in tedesco ("du"), ogni traduzione farà esattamente così.

Tutto funziona insieme

Ecco cosa conta: i termini del glossario, le convenzioni di formattazione, le istruzioni personalizzate e le impostazioni di formalità si applicano a ogni traduzione allo stesso tempo. Non deve scegliere l'uno o l'altro. Li imposta tutti una volta sola, e ogni paragrafo che viene tradotto segue lo stesso insieme di regole.

Il risultato sono traduzioni che si leggono come se le avesse scritte qualcuno del suo team locale. Non come una macchina che ha tradotto ogni frase senza sapere nulla della sua azienda.

Ogni lingua può avere il proprio contenuto

Questa è la caratteristica che sorprende di più le persone.

In Rasepi, un documento tradotto non è una copia bloccata dell'originale. Ogni versione linguistica può avere contenuti che esistono solo in quella lingua.

**Perché questo è importante?

Perché mercati diversi hanno bisogno di cose diverse:

La sua documentazione tedesca potrebbe aver bisogno di una sezione sulla conformità al DSGVO (GDPR) che non si applica alla versione USA.
Il suo team giapponese potrebbe aver bisogno di una nota sugli strumenti locali che nessun altro utilizza.
Il suo ufficio in Brasile potrebbe aver bisogno di un contesto sulle normative fiscali regionali.

Nella maggior parte degli strumenti di traduzione, l'aggiunta di contenuti a una versione linguistica significa che questi vengono sovrascritti la volta successiva che qualcuno ritraduce dall'inglese. I team lo capiscono subito e smettono di aggiungere contenuti locali. Creano documenti ombra in Notion o Slack o da qualche altra parte, e ora avete due sistemi di cui nessuno si fida pienamente.

In Rasepi, i contenuti unici sono contrassegnati come appartenenti a quella lingua. Non viene mai sovrascritto da una ritraduzione. Non viene mai cancellato quando la fonte inglese cambia. Vive accanto al contenuto tradotto come parte naturale del documento.

Lo stesso vale per la struttura. Se i suoi traduttori giapponesi preferiscono gli elenchi numerati mentre la versione inglese utilizza i punti (una convenzione comune nella scrittura tecnica giapponese), possono cambiare il formato. Rasepi conserva questa scelta negli aggiornamenti futuri.

Ogni versione linguistica è un documento di prima classe, non uno specchio di sola lettura.

Automatico e umano: lavorano insieme

Rasepi non la costringe a scegliere tra traduzione automatica e traduzione umana. Le supporta entrambe e conosce la differenza.

Quando un paragrafo è tradotto a macchina e la fonte cambia, Rasepi lo ritraduce automaticamente. Non è necessario l'intervento umano. Il glossario e le regole di stile mantengono la coerenza.

Quando un paragrafo è stato modificato manualmente da un traduttore umano, che magari lo ha riscritto per una sfumatura culturale o ha aggiunto un contesto che la macchina non avrebbe colto, Rasepi rispetta quel lavoro. Se la fonte cambia, il sistema segnala il paragrafo come da rivedere, ma non sovrascrive mai silenziosamente le modifiche umane. Il traduttore vede cosa è cambiato nella fonte e decide come aggiornare la propria versione.

Ciò significa che la qualità della sua traduzione migliora nel tempo. La traduzione automatica gestisce il grosso. I traduttori umani si concentrano sui paragrafi che necessitano di un tocco umano. E nessuno dei due si intromette nel lavoro dell'altro.

Due modalità: sempre attuale o traduzione su richiesta

Per ogni lingua, può scegliere quando effettuare le traduzioni:

Ogni volta che qualcuno salva il documento di origine, i paragrafi modificati vengono ritradotti immediatamente. Ideale per le sue lingue più importanti, dove i lettori si aspettano un'accuratezza al minuto.
Tradurre al momento della visualizzazione. I paragrafi modificati vengono segnalati ma non tradotti fino a quando qualcuno non apre effettivamente il documento in quella lingua. Ottimo per le lingue utilizzate meno frequentemente. Nessun costo di traduzione sprecato per contenuti che non vengono letti.

Entrambe le modalità utilizzano lo stesso glossario, le stesse regole di stile e la stessa qualità. L'unica differenza è la tempistica.

Come si presenta in pratica

Supponiamo che lei gestisca un'azienda con team a Londra, Monaco, Parigi e Tokyo. La sua documentazione è scritta in inglese.

Un product manager di Londra aggiorna la guida alla distribuzione. Una sezione riguarda una nuova fase CI/CD.

Ecco cosa succede:

La sezione modificata viene ritradotta in pochi secondi. "Sprint Review" diventa "Sprint-Überprüfung" perché è nel suo glossario. Formale "Sie" perché questa è la sua impostazione di formalità. Le date nel formato 24 ore perché è la sua regola configurata. L'istruzione personalizzata "usi un tono diretto e imperativo" modella il fraseggio. La sezione DSGVO aggiunta dal team di Monaco? Inalterata.
Stessa sezione, ritradotta immediatamente. Formalità "Vous". Applicazione dei termini del glossario francese. Simboli di valuta dopo il numero, secondo le sue istruzioni personalizzate. Il resto del documento rimane esattamente come l'ufficio di Parigi lo ha revisionato l'ultima volta.
La sezione modificata viene contrassegnata come obsoleta. Quando qualcuno a Tokyo apre il documento, questo viene tradotto al volo. La formattazione personalizzata degli elenchi numerici viene conservata. La loro nota di tooling locale rimane al suo posto.

Una modifica. Tre lingue aggiornate. Zero ritraduzioni di documenti completi. Terminologia coerente, tono coerente e rispettoso delle aggiunte locali di ogni team.

Parlando di qualità linguistica

Il motore di traduzione che sta dietro a tutto questo è DeepL, la stessa tecnologia che alimenta la funzione Talk to Docs di Rasepi. Può parlare alla sua documentazione e ricevere risposte ad alta voce. DeepL Voice gestisce l'interazione vocale, il che significa che la stessa coerenza terminologica, le regole di stile e la qualità linguistica che ottiene nelle traduzioni scritte si applicano anche alle conversazioni vocali. I termini del suo glossario e le istruzioni personalizzate suonano bene sia che il suo team stia leggendo che ascoltando.

Le traduzioni che suonano come il suo team non sono un lusso. Per le aziende che operano in più lingue, sono la differenza tra la documentazione di cui ci si fida e quella su cui si lavora. Glossari, regole di stile, istruzioni personalizzate, ritraduzioni intelligenti e contenuti unici per lingua lo rendono possibile. Automaticamente, fin dal primo giorno.

La sua documentazione deve suonare come il suo team in ogni lingua. Non come una macchina. Non come un'altra azienda. Come lei.

Vedere la pubblicazione multilingue in azione →

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 si può 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   /api/admin/glossaries                       Create glossary
POST   /api/admin/glossaries/{id}/entries           Add term
PUT    /api/admin/glossaries/{id}/entries/{entryId}  Update term
DELETE /api/admin/glossaries/{id}/entries/{entryId}  Remove term
POST   /api/admin/glossaries/{id}/import            Import CSV
GET    /api/admin/glossaries/{id}/export            Export CSV
POST   /api/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 appare:

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 coprono 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 dell'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 utilizza 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 richiede il 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 redazione 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. L'adattamento della 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 →

Smettere di mantenere cinque copie dello stesso documento

2026-03-31T00:00:00Z

Apra subito il wiki aziendale e cerchi "onboarding". Quanti risultati ottiene?

Se è un'azienda globale, immagino che non sia uno solo. Probabilmente si tratta di qualcosa di simile:

Onboarding Guide (EN)
CODICEBLOCCO_1
CODICEBLOCCO_2
BLOCCO_3
BLOCCO_4

Cinque documenti. Tutti riguardano più o meno la stessa cosa. Tutti leggermente diversi. Tutti mantenuti da persone diverse con tempistiche diverse. Alcuni attuali, altri in ritardo di tre mesi, uno di cui nessuno è più sicuro.

Questo è ciò che accade quando la piattaforma di documentazione non è in grado di gestire correttamente i contenuti multilingue. Si finisce per copiare l'intero documento per ogni mercato, e ogni copia si allontana lentamente dalle altre.

La trappola del copia-e-localizza

L'inizio è abbastanza innocente. Avete un'ottima guida all'onboarding in inglese. L'ufficio di Berlino ne ha bisogno in tedesco, quindi qualcuno la copia, la traduce e aggiunge le parti specifiche per la Germania: Formazione DSGVO, informazioni Betriebsrat, iscrizione all'assicurazione sanitaria locale.

Poi Tokyo ne ha bisogno. Copia di nuovo. Tradurre. Aggiunga le informazioni specifiche per il Giappone: registrazione hanko, procedura per il pass dei pendolari, guida al galateo in ufficio.

São Paulo è il prossimo. Stessa cosa. Copiare, tradurre, aggiungere contenuti locali sui requisiti del CLT, sui buoni pasto e sui documenti fiscali.

Ora ha quattro documenti. L'originale inglese viene aggiornato regolarmente. La versione tedesca è stata aggiornata lo scorso trimestre. La versione giapponese... qualcuno pensa che Tanaka-san l'abbia aggiornata in ottobre. La versione brasiliana è stata creata da un appaltatore che se n'è andato e nessuno l'ha più toccata.

Ogni copia è un onere di manutenzione. E ognuna di esse contiene un mix di contenuti condivisi (le cose che sono uguali dappertutto) e di contenuti locali (le cose specifiche di quel mercato). Ma la piattaforma non conosce la differenza. Si tratta solo di testo su una pagina.

Quindi, quando qualcuno aggiorna la sezione della politica di sicurezza nell'originale inglese, nessuno aggiorna le altre quattro. O peggio, qualcuno aggiorna quella tedesca ma non quella giapponese. Ora avete cinque documenti che dicono tutti cose leggermente diverse sulla stessa politica aziendale.

Il vero problema: i contenuti condivisi e quelli locali sono mescolati insieme

Il fatto è che la maggior parte di questi documenti sono identici al 70-80%. Le fasi di onboarding, l'impostazione degli strumenti, le politiche di sicurezza, la sezione dei valori aziendali, l'elenco di "chi contattare". Tutto ciò è identico indipendentemente dal fatto che si trovi a Berlino, Tokyo o San Paolo.

Gli aspetti locali rappresentano forse il 20-30% del documento. Requisiti specifici di conformità, vantaggi locali, processi regionali, contatti del team per quell'ufficio.

Ma quando tutto vive in un grande documento piatto per lingua, non c'è modo di capire quali parti sono condivise e quali sono locali. Un aggiornamento del contenuto condiviso significa controllare e aggiornare manualmente ogni copia. E nessuno lo fa in modo coerente. Ecco perché le copie vanno alla deriva.

Un documento. Tutto qui.

In Rasepi, la guida all'onboarding è un unico documento. Non uno per lingua. Uno.

Il contenuto condiviso, quel 70-80% che è uguale ovunque, viene scritto una volta in inglese e tradotto automaticamente in tutte le lingue utilizzate dal suo team. Quando qualcuno aggiorna la sezione della politica di sicurezza in inglese, viene ritradotto in tedesco, giapponese, portoghese e francese in pochi secondi. Nessuna copia manuale. Niente "qualcuno dovrebbe aggiornare le altre versioni".

I contenuti locali vivono nella rispettiva versione linguistica. La sezione di formazione DSGVO esiste solo nella versione tedesca. Il processo hanko esiste solo nella versione giapponese. I requisiti CLT esistono solo nella versione portoghese. Queste sezioni sono contrassegnate come contenuto unico, appartengono a quella lingua e non vengono mai sovrascritte dalla ritraduzione.

Abbiamo spiegato esattamente come funziona nel nostro post su [come funzionano le traduzioni Rasepi] (/it/blog/how-rasepi-translations-work-and-why-they-sound-like-your-team/). La versione breve: ogni paragrafo ha la propria identità. I paragrafi condivisi vengono tradotti e monitorati. I paragrafi unici appartengono alla loro lingua e nessun altro li tocca.

Il risultato? La sua ricerca su wiki di "onboarding" restituisce un solo risultato. Solo "Onboarding". Se lo apre in inglese, vedrà la versione inglese con tutti i contenuti condivisi. Aprendolo in tedesco, vedrà lo stesso contenuto condiviso in tedesco più le sezioni specifiche per la Germania. Lo apra in giapponese, lo stesso contenuto condiviso in giapponese più le sezioni specifiche per il Giappone.

Un documento. Non cinque. Non cinque documenti che marciscono lentamente a velocità diverse.

Cosa cambia in realtà

Non è solo più ordinato. Cambia radicalmente il modo in cui la sua documentazione funziona in tutti gli uffici.

Gli aggiornamenti arrivano a tutti

Quando aggiorna la parte condivisa della guida all'onboarding, viene aggiornata in tutte le lingue. Non alla fine, non dopo che qualcuno si ricorda di farlo. Automaticamente. Il paragrafo modificato viene ritradotto. Tutto il resto rimane esattamente dov'era.

Ciò significa che l'ufficio di Tokyo legge la stessa politica aziendale dell'ufficio di Londra. Non la versione di sei mesi fa che nessuno ha aggiornato.

I team locali sono proprietari dei loro contenuti locali

Il suo team di Monaco può aggiungere una sezione sullo sconto della palestra locale senza preoccuparsi che venga cancellata dal prossimo aggiornamento in inglese. Il loro contenuto unico è loro. Rimane nella versione tedesca, non influenzato da eventuali modifiche alla fonte inglese.

Lo stesso vale per tutti gli altri uffici. I contenuti locali sono veramente locali. Non interferisce con il contenuto condiviso, e il contenuto condiviso non interferisce con esso.

I nuovi assunti ricevono le informazioni giuste

Un nuovo assunto a San Paolo apre la guida all'onboarding e vede tutto ciò di cui ha bisogno. Le sezioni condivise (strumenti, sicurezza, valori) sono in portoghese. Le sezioni specifiche per il Brasile (CLT, documenti fiscali, buoni pasto) sono lì accanto. Un unico documento, tutto nella loro lingua, niente di mancante, niente di obsoleto.

Non hanno bisogno di sapere che altri tre uffici hanno sezioni locali diverse. Vedono solo la loro versione. Pulita e completa.

Il suo numero di pagine diminuisce

Questo è il semplice calcolo. Se ha 50 documenti chiave e li mantiene in 5 lingue con l'approccio copia-e-localizza, ha 250 documenti. In Rasepi, ne ha 50. Ognuno con versioni linguistiche che condividono contenuti comuni e mantengono le proprie sezioni locali.

250 documenti da mantenere contro 50. Si tratta di 200 pagine di spese generali di manutenzione che scompaiono.

Non si tratta solo di onboarding

L'onboarding è l'esempio più ovvio, perché ogni azienda globale ha questo problema. Ma lo stesso schema si presenta ovunque:

Guide di distribuzione. I passaggi fondamentali sono gli stessi, ma il team di Berlino utilizza un server di staging locale e Tokyo ha un processo di approvazione diverso.
Documentazione sulla conformità.** Sezione GDPR per l'Europa, LGPD per il Brasile, APPI per il Giappone. Tutti nello stesso documento, ognuno dei quali appare solo quando è rilevante.
Benefici e politiche HR. La politica di congedo parentale è diversa in ogni Paese. I valori aziendali sono gli stessi ovunque.
Il prodotto funziona allo stesso modo ovunque, ma i metodi di pagamento, gli orari di assistenza e le normative regionali variano.

Ognuno di questi è un documento che la maggior parte delle aziende conserva in copie separate per ogni mercato. E ognuno di essi potrebbe essere un unico documento con contenuti condivisi e locali.

L'effetto composto

Ecco dove il problema diventa reale. Un'azienda con 200 documenti in 4 mercati non sta mantenendo 200 documenti. Ne sta gestendo 800. Ma il personale è impiegato per 200. Quindi, ciò che accade realmente è:

Le versioni in inglese sono aggiornate
Le versioni tedesche sono per lo più aggiornate
Le versioni francesi sono indietro
Le versioni giapponesi sono un punto interrogativo

Le sembra familiare?

In Rasepi, vengono gestiti 200 documenti. Il contenuto condiviso viene tradotto automaticamente. I contenuti locali vengono aggiunti dai team locali. Ogni versione è aggiornata come quella inglese, più le aggiunte locali che il team regionale ha fatto.

Anche i costi di traduzione sono inferiori. Quando aggiorna un paragrafo in inglese, solo quel paragrafo viene ritradotto in tutte le lingue. Non l'intero documento, né tutti i 200 documenti. Solo il paragrafo effettivamente cambiato. Abbiamo scritto in dettaglio come funziona, includendo il glossario e le regole di stile che fanno sì che il contenuto tradotto suoni naturale.

Un rapido controllo di base

Se gestisce un team globale, si chieda:

**Quanti documenti duplicati ha? ** Cerchi lo stesso argomento e conti le copie specifiche della lingua.
**Quanto sono aggiornate le versioni non inglesi? ** Controlli la data di ultima modifica dei documenti in tedesco, francese o giapponese. Quanto sono indietro?
**I team locali aggiungono contenuti alle loro versioni? ** O hanno rinunciato perché vengono sovrascritti?
**Quanto tempo impiega l'onboarding negli uffici non inglesi? ** Se è più lungo, è probabile che la documentazione non li stia servendo correttamente.

Se le risposte la mettono a disagio, non è il solo. La maggior parte delle aziende non si rende conto di quante spese generali ha creato, finché non conta effettivamente le copie.

La documentazione deve crescere con la sua azienda, non moltiplicarsi. Ogni copia che mantiene è una copia che può rimanere indietro, confondere un nuovo assunto o contraddire la versione che qualcun altro sta leggendo. Un documento per argomento, con contenuti condivisi tradotti e contenuti locali al loro posto, è il modo in cui la documentazione dovrebbe funzionare in un'azienda globale.

Il suo wiki non dovrebbe avere bisogno di cinque copie dello stesso documento. Una è sufficiente. Passi condivisi tradotti, passi locali per lingua. Tutto qui.

Vedere la pubblicazione multilingue in azione →

Il caso commerciale della localizzazione a livello di blocco

2026-03-24T00:00:00Z

C'è uno schema in ogni azienda che opera a livello transfrontaliero. La documentazione in inglese è solida. La versione tedesca è in ritardo di tre mesi. La versione giapponese è stata tradotta una volta, da un appaltatore, e nessuno l'ha più toccata. La versione brasiliana in portoghese non esiste ancora, anche se San Paolo è l'ufficio in più rapida crescita.

Tutti concordano che si tratta di un problema. Nessuno ha una buona soluzione. Finora, la localizzazione è stata trattata come un progetto, uno sforzo una tantum che si mette in preventivo, si esegue e poi si trascura tranquillamente fino alla prossima grande revisione.

Questo approccio è rotto. Ecco perché e cosa penso che funzioni davvero.

La traduzione non è localizzazione

Chiariamo la terminologia. La traduzione consiste nel prendere un testo in una lingua e produrre un testo equivalente in un'altra. La localizzazione consiste nel far funzionare le conoscenze in un mercato specifico. Si sovrappongono, ma non sono la stessa cosa.

Un documento tradotto si legge correttamente. Un documento localizzato si legge in modo naturale. Tiene conto del contesto culturale, delle normative regionali, degli strumenti locali e del modo in cui le persone in quel mercato lavorano.

Questa distinzione è importante perché la maggior parte delle piattaforme di documentazione trattano la localizzazione come un compito di traduzione. Si scrive in inglese, si preme un pulsante e si ottiene un risultato in francese. Fatto. Solo che non è fatto, perché..:

Il team francese ha un processo di distribuzione diverso che il documento in inglese non contempla.
I requisiti di conformità tedeschi aggiungono una fase di approvazione supplementare che non esiste altrove.
l'ufficio giapponese utilizza uno strumento interno diverso per lo stesso flusso di lavoro
I lettori portoghesi brasiliani hanno bisogno di un contesto sulle norme fiscali locali che non sono rilevanti altrove.

**Una traduzione diretta del documento inglese è tecnicamente corretta in tutti questi casi, e praticamente inutile in tutti gli altri.

Il problema della traduzione a livello di documento

La localizzazione tradizionale funziona a livello di documento. Lei ha un documento in inglese. Lo traduce interamente in tedesco. Quando la versione inglese cambia, invia l'intero documento per una nuova traduzione. Questo crea tre problemi:

1. È costoso

Se la sua guida onboarding ha 15 sezioni e lei cambia un paragrafo, pagherà per ritradurre tutte e 15 le sezioni. Moltiplicando questo dato per 8 lingue, ogni modifica diventa una conversazione di bilancio.

2. È lento

Inviare documenti completi per la traduzione richiede tempo. Anche con la moderna traduzione automatica, il ciclo di revisione di un documento completo è significativamente più lungo rispetto alla revisione di una singola sezione modificata. I team in altre lingue sono sempre in ritardo.

3. Non supporta i contenuti unici

Questo è il vero problema. Se la versione tedesca ha bisogno di una sezione extra sulla conformità DSGVO, dove va a finire? In un sistema di traduzione a livello di documento, qualsiasi contenuto aggiunto alla versione tedesca viene sovrascritto la volta successiva che qualcuno ritraduce dall'inglese. Il team tedesco impara in fretta: non aggiunga nulla, perché verrà cancellato.

Localizzazione a livello di blocco: un'architettura diversa

Rasepi non traduce documenti. Traduce blocchi: singoli paragrafi, titoli e sezioni, ognuno dei quali viene tracciato in modo indipendente con la propria identità e hash del contenuto.

Ecco cosa significa in pratica:

Quando modifica un singolo paragrafo in inglese, Rasepi rileva quale blocco è cambiato confrontando gli hash del contenuto SHA256. Solo quel blocco viene inviato per la traduzione tramite DeepL. Gli altri 14 blocchi del documento rimangono esattamente come erano. Il suo costo di traduzione si riduce fino al 94%.

Quando il traduttore tedesco deve aggiungere una sezione DSGVO, la aggiunge come nuovo blocco nella versione tedesca. Questo blocco esiste solo in tedesco. Non influisce sulla fonte inglese. Non viene sovrascritto quando l'inglese cambia. È contrassegnato come contenuto unico, in modo che tutti sappiano che è intenzionale.

Quando la versione giapponese ha bisogno di una struttura diversa, ad esempio un elenco numerato invece di punti elenco perché è la convenzione della scrittura tecnica giapponese, il traduttore può cambiare il tipo di blocco. Il sistema tiene traccia di questo come "adattamento della struttura" e lo conserva per gli aggiornamenti futuri.

Ogni versione linguistica diventa un documento di prima classe, non una copia ombra.

Come funziona, tecnicamente

Ogni blocco in Rasepi ha:

Un UUID che persiste in tutte le modifiche e traduzioni
Un hash del contenuto (SHA256) che cambia quando il testo viene modificato
Un indice di posizione, in modo che i blocchi rimangano nel giusto ordine
Un flag di cancellazione morbida**, in modo che la rimozione di un blocco in inglese non interrompa l'allineamento in altre lingue.

Quando viene creato un blocco di traduzione, viene memorizzato l'hash del contenuto del blocco sorgente. Ad ogni salvataggio, il sistema confronta gli hash. Se corrispondono, la traduzione è corrente. In caso contrario, la traduzione viene contrassegnata come obsoleta e solo quel blocco specifico necessita di attenzione.

Questo è il meccanismo alla base della riduzione dei costi del 94%. La maggior parte delle modifiche cambia una o due sezioni. Il resto del documento, in tutte le lingue, non viene toccato.

Contenuto unico per lingua

Qui le cose si differenziano veramente da qualsiasi altra piattaforma.

In Rasepi, ogni versione linguistica può contenere:

Blocchi tradotti. Traduzioni dirette della lingua di partenza, monitorate per verificare l'obsolescenza.
Blocchi unici.** Contenuto che esiste solo in quella lingua, aggiunto dal team locale.
Blocchi adattati alla struttura.** Stesso contenuto di partenza, formattazione o tipo di blocco diversi.

Un singolo documento potrebbe avere questo aspetto nelle varie lingue:

Blocco	Inglese (sorgente)	Tedesco	Giapponese
1	Introduzione	Tradotto	Tradotto
2	Fasi di impostazione	Tradotto	Struttura adattata (elenco numerato)
3	-	Conformità DSGVO (unico)	-
4	Installazione	Tradotto	Tradotto
5	-	-	Nota sugli utensili locali (unica)
6	Risoluzione dei problemi	Tradotto	Tradotto

Ogni team riceve esattamente la documentazione di cui ha bisogno. Senza compromessi. Nessuna soluzione. Nessuna limitazione unica per tutti.

Tracciamento della freschezza nelle varie lingue

Ogni versione linguistica traccia la propria freschezza in modo indipendente. La fonte inglese potrebbe ottenere un punteggio di 94 (recensione recente, tutti i link validi, alto numero di lettori). La versione francese potrebbe ottenere un punteggio di 71 (due blocchi obsoleti, un link rotto specifico per il contenuto francese). La versione giapponese potrebbe ottenere un punteggio di 88 (tutte le traduzioni sono aggiornate, ma i lettori sono in calo).

Questo monitoraggio della freschezza per lingua significa che:

Sapere esattamente quali sono le lingue che necessitano di attenzione
Le traduzioni obsolete vengono evidenziate automaticamente, non vengono scoperte per caso.
Gli strumenti di intelligenza artificiale possono tenere conto della freschezza specifica della lingua quando servono le risposte.
I dashboard mostrano la salute dei contenuti suddivisi per lingua, non solo per documento

Il caso aziendale

Le aziende che operano in più lingue devono affrontare una semplice realtà: la sua documentazione è una risorsa o una passività in ogni mercato che serve.

Se il suo team di Berlino lavora su una traduzione tedesca che è tre mesi indietro rispetto alla fonte inglese, sta prendendo decisioni basate su informazioni non aggiornate. Quando il suo ufficio di Tokyo non può aggiungere il contesto locale ai documenti condivisi perché il sistema di traduzione lo sovrascriverebbe, smette di usare il wiki e crea la propria documentazione ombra. Quando il suo team di San Paolo non dispone di documenti in portoghese, l'onboarding richiede il doppio del tempo.

Il costo non è solo quello della traduzione. E' anche:

Minore onboarding nei mercati non anglosassoni
Sforzo duplicato, in quanto i team mantengono una documentazione parallela negli strumenti locali.
Silos di conoscenza che si formano quando il wiki ufficiale non è utile a tutti.
Rischio di conformità** quando i requisiti specifici della regione non vengono catturati.
Perdita di fiducia nel sistema di documentazione stesso

La localizzazione a livello di blocco risolve tutti questi problemi, non rendendo la traduzione più economica (anche se lo fa), ma rendendo ogni versione linguistica un documento vivo, curato e affidabile.

Iniziare

Se oggi gestisce un team multilingue su una qualsiasi piattaforma di documentazione, ecco un rapido controllo di base:

Scelga il suo documento più importante. Lo controlli in ogni lingua. Ogni versione è aggiornata?
Chieda ai suoi team non inglesi: si fidano dei documenti tradotti? Li utilizzano?
**I team mantengono wiki locali, pagine Notion o messaggi appuntati su Slack perché i documenti ufficiali non li servono?
Calcolare la spesa per le traduzioni. Quanto paga per ogni aggiornamento, e quanta parte di questa spesa è costituita dalla ritraduzione di contenuti che non sono cambiati?

Se le risposte sono scomode, non è l'unico. La maggior parte delle aziende non scopre il divario fino a quando non causa un problema reale: un problema di conformità, un'implementazione sbagliata, un nuovo assunto che ha trascorso due settimane seguendo istruzioni obsolete.

La conoscenza multilingue non è una cosa piacevole. Per qualsiasi azienda che opera a livello transfrontaliero, è la base del modo in cui i team si allineano, prendono decisioni e spediscono. La questione è se la sua piattaforma di documentazione la tratta in questo modo.

Ogni lingua merita di essere un cittadino di prima classe nella sua base di conoscenza. Non una copia. Non un'ombra. Un documento reale, curato e affidabile.

Ecco cosa offre Rasepi. Traduzione a livello di blocco, contenuti unici per lingua, monitoraggio indipendente della freschezza e una riduzione del 94% dei costi di traduzione. Tutto automatico. Tutto dal primo giorno.

Vedere la pubblicazione multilingue in azione →

Freschezza dei contenuti, parte 2: oltre le date di scadenza

2026-03-18T00:00:00Z

Questa è la parte 2 della nostra serie sulla freschezza dei contenuti. [La Parte 1] (/it/blog/perché la freschezza conta più che mai/) spiega perché la freschezza conta e cosa significa effettivamente. Questo post riprende da dove si era interrotto: perché le date di scadenza da sole non sono sufficienti e come si presenta il monitoraggio continuo.

Diciamo che lei fa una cosa responsabile. Ogni documento nel suo wiki riceve una data di revisione. Sei mesi dalla creazione, forse dodici per il materiale di riferimento stabile. Quando arriva la data, il proprietario riceve una notifica: riveda questo documento o verrà segnalato.

Questo è meglio di quello che fa la maggior parte delle aziende. La maggior parte delle aziende non fa nulla. Il documento rimane lì, in lento decadimento, e nessuno se ne accorge finché qualcuno non segue le istruzioni e qualcosa si rompe.

Ma ecco la scomoda verità: Le date di scadenza sono necessarie e del tutto insufficienti. Ho visto documenti diventare pericolosamente obsoleti giorni dopo la loro ultima revisione, e una data di revisione non li cattura.

Cosa risolvono le date di scadenza

Le date di scadenza risolvono il problema della responsabilità. Rispondono alla domanda: "Chi è responsabile di confermare che questo sia ancora accurato, e quando?".

Questo è davvero prezioso. Senza di essa, la documentazione entra in quello che chiamiamo il vuoto di proprietà, uno stato in cui tutti presumono che qualcun altro la mantenga, quindi nessuno lo fa. La definizione di una data di revisione assegna a una singola persona un singolo obbligo in una data specifica. Semplice. Chiaro. Efficace.

Ecco come si presentano le date di scadenza nella pratica:

Viene creato un documento con una data di revisione a 90 giorni dalla scadenza.
14 giorni prima della scadenza, il proprietario riceve una notifica
Alla data di scadenza, il documento viene contrassegnato come "da rivedere".
Il proprietario lo rivede, conferma che è ancora accurato e proroga la data.
Oppure lo aggiorna, lo riassegna o lo archivia.

Questo è un sistema solido. Cattura il lento decadimento, il documento a cui nessuno ha pensato in un anno. Crea una cadenza regolare di revisione. Rende visibile la proprietà.

**Ma ha un punto cieco grande come un continente.

Cosa manca alle date di scadenza

Tra le date di revisione, un documento vive in una scatola nera. Lo ha revisionato il 15 gennaio. La prossima revisione è il 15 aprile. Il 3 febbraio, potrebbe accadere una qualsiasi di queste cose:

I link si rompono silenziosamente

Un URL esterno a cui ha fatto riferimento restituisce un 404. Un link interno punta ad un documento che è stato archiviato. Un repository di codice è stato rinominato e ogni link a GitHub nel suo documento è morto. Il suo documento è ancora valido. La data di scadenza è prevista tra due mesi. Nessuno sa che i link sono interrotti.

Modifiche ai contenuti correlati

Lei ha scritto una guida all'implementazione che fa riferimento al suo documento di architettura. A febbraio, qualcuno riscrive completamente il documento di architettura. Nuovi modelli, nuove infrastrutture, nuove convenzioni. La sua guida alla distribuzione fa ancora riferimento alla vecchia architettura. Non è ancora tecnicamente sbagliata, ma sta andando alla deriva. Quando arriva la data di revisione, il divario potrebbe essere significativo.

Il numero di lettori scende a zero

Il suo documento veniva letto da 40 persone al mese. Poi un processo è cambiato e nessuno ne ha più bisogno, ma nessuno lo ha nemmeno archiviato. Rimane nei risultati di ricerca, occupando spazio e confondendo occasionalmente un nuovo assunto che non sa che è irrilevante. La data di scadenza non si preoccupa dei lettori. Il proprietario verrà contattato puntualmente, a prescindere.

Le traduzioni rimangono indietro

La fonte inglese è stata aggiornata il 10 febbraio. Le traduzioni in francese, tedesco e giapponese sono ormai obsolete. Ma la data di scadenza di queste versioni tradotte non è prima di maggio. Per tre mesi, i team non inglesi leggono contenuti obsoleti e non lo sanno.

I lettori segnalano i problemi

Un lettore lascia un commento: "Il passo 3 non funziona più, il flag CLI è stato deprecato". Questo commento rimane lì. La data di scadenza è ancora lontana. La prossima persona che leggerà il documento potrebbe non vedere il commento. Quella successiva sicuramente no.

La scadenza è un punto di controllo programmato. Questi sono eventi non programmati. L'intervallo tra i due è il punto in cui la documentazione stantia causa i danni maggiori.

Freschezza: monitoraggio continuo

Il punteggio di freschezza colma il vuoto che le date di scadenza lasciano aperto. Invece di controllare la salute di un documento una volta ogni 90 giorni, la freschezza lo monitora continuamente. Ogni giorno, in background, senza che nessuno debba fare nulla.

Ecco come funziona in Rasepi:

Ogni documento riceve un punteggio di freschezza in tempo reale da 0 a 100, calcolato in base a più segnali:

Segnale	Cosa rileva	Perché è importante
Salute del link	URL rotti, reindirizzati o non raggiungibili	I link rotti erodono la fiducia e fanno perdere tempo
Stato di revisione	Se il documento è stato rivisto nei tempi previsti	Il controllo di responsabilità di base
Tendenze di lettura	Se qualcuno sta effettivamente leggendo questo documento	Un basso numero di lettori suggerisce che il documento potrebbe essere irrilevante
Recenza di modifica	Quando il documento è stato modificato per l'ultima volta rispetto ai contenuti correlati	Rileva la deriva rispetto alla base di conoscenza circostante
Allineamento della traduzione	Se tutte le versioni linguistiche sono aggiornate	Le traduzioni obsolete significano che i team di altri mercati lavorano su informazioni vecchie
Bandiere dei lettori	Se i lettori hanno segnalato dei problemi	Rilevamento di stallo da parte della folla
Riferimenti incrociati	Se i documenti a cui si collega sono a loro volta obsoleti	La staticità è contagiosa

Ogni segnale contribuisce al punteggio complessivo. Un documento può perdere punti di freschezza per un link interrotto oggi, anche se la sua data di revisione non è prevista prima di settimane. Questo è il punto centrale.

Come le due cose lavorano insieme

Scadenza e freschezza non sono approcci in competizione. Sono livelli complementari:

Le date di scadenza sono il livello di governance. Creano una cadenza regolare di revisione umana. Qualcuno deve esaminare questo documento secondo un calendario e confermare che è ancora accurato. Questo cattura le cose che l'automazione non può fare: se il contenuto è ancora corretto, se il consiglio è ancora valido, se il processo che descrive riflette ancora la realtà.

Il Freshness scoring è il livello di monitoraggio. Cattura tutto ciò che si verifica tra le date di revisione: i collegamenti interrotti, la deriva della traduzione, i documenti abbandonati, il decadimento contestuale che si verifica quando il mondo si muove e un documento no.

Insieme creano un sistema in cui:

Ogni documento viene rivisto da un essere umano secondo un calendario regolare (scadenza).
Tra una revisione e l'altra, i segnali automatizzati colgono i problemi nel momento in cui si verificano (freschezza).
Entrambi i sistemi confluiscono in un unico punteggio di fiducia che tutti possono vedere.
Tale punteggio influisce sul posizionamento del documento nella ricerca e sul fatto che gli strumenti di intelligenza artificiale lo utilizzino come fonte.

L'impatto del punteggio

Qui si entra nel pratico. In Rasepi, il punteggio di freschezza di un documento influisce direttamente sulla sua visibilità:

Punteggio 80-100: Visibilità completa. Appare normalmente nei risultati di ricerca. Idoneo come fonte per le risposte dell'AI. Nessun flag.
Punteggio 50-79: Visibilità ridotta. Appare nella ricerca con un indicatore di stallo. Gli strumenti AI possono deprioritarla come fonte. Il proprietario viene avvisato.
Core inferiore a 50: Segnalato. Scende significativamente nei risultati della ricerca. Escluso completamente dalle risposte dell'AI. Il proprietario riceve una notifica urgente.

Questo crea un ciclo di feedback. Quando il punteggio di un documento si riduce, il proprietario è spinto a risolverlo, non perché è arrivata una data arbitraria, ma perché qualcosa è effettivamente cambiato. Il link rotto, la traduzione obsoleta, il calo dei lettori, sono segnali reali che richiedono attenzione ora, non tra sei settimane.

Un esempio pratico

Vediamo uno scenario:

Marzo 1: Il suo "Incident Response Playbook" ha ottenuto un punteggio di 92. È stato revisionato due settimane fa, tutti i link sono validi, il numero di lettori è elevato e tutte e quattro le versioni linguistiche sono aggiornate.

8 marzo: Qualcuno ristruttura la pagina dello stato dell'ingegneria. Tre URL del playbook ora reindirizzano. Il punteggio di freschezza scende a 78. Il proprietario riceve una notifica: "Rilevati 3 link non funzionanti".

10 marzo: Il proprietario ripara i link. Il punteggio sale a 89.

15 marzo: La versione inglese viene aggiornata con un nuovo percorso di escalation. Le traduzioni in francese e tedesco sono ora obsolete (mancata corrispondenza dell'hash del contenuto). Il punteggio scende a 74.

17 marzo: Le traduzioni vengono aggiornate. Il punteggio torna a 91.

20 marzo: I dati di lettura mostrano che la versione giapponese non viene visitata da 30 giorni. Il punteggio scende a 86. Un segnale sottile, ma tracciato.

1 aprile: Arriva la data di revisione prevista. Il proprietario rivede il contenuto, ne conferma l'accuratezza e proroga la scadenza al 1° luglio. Il punteggio rimane a 86 perché il segnale di lettura è ancora presente.

In nessun momento il team ha atteso una data di revisione per individuare un problema. Il sistema di freschezza ha segnalato i problemi entro pochi giorni. La data di revisione ha fornito il punto di controllo della governance. Entrambi i livelli fanno il loro lavoro.

Perché "fissare una data di revisione" non è più sufficiente

Cinque anni fa, le date di scadenza potevano essere sufficienti. La documentazione veniva letta dalle persone e le persone potevano esercitare un giudizio. Se un documento sembrava un po' strano, si chiedeva in giro.

Oggi, la documentazione è un'infrastruttura. Alimenta gli strumenti di AI, l'automazione dell'onboarding, i sistemi di conformità e i motori di ricerca che forniscono risultati senza contesto. Questi sistemi non esercitano il giudizio. Consumano i contenuti così come sono e li ridistribuiscono in scala.

Un documento con link non funzionanti e traduzioni obsolete, a cui mancano ancora tre settimane alla data di revisione, può fare molti danni in quelle tre settimane, soprattutto se un assistente AI sta fornendo risposte sicure sulla base di esso.

Le date di scadenza sono l'approccio minimo possibile alla governance della documentazione. Il punteggio di freschezza è ciò che serve quando la documentazione viene consumata da sistemi che non sono in grado di pensare da soli.

Iniziare

Se ha già delle date di scadenza sui suoi documenti (buon per lei, sul serio, la maggior parte dei team non lo fa nemmeno), ecco come aggiungere la freschezza:

**Esegua un controllo dei link interrotti sui suoi 50 documenti principali. Il numero probabilmente la sorprenderà.
**Se ha documenti multilingue, confronti le date di ultima modifica tra la fonte e le traduzioni. Quante sono indietro di oltre un mese?
Guarda la readership. Quali documenti non ricevono traffico? Sono ancora necessari o dovrebbero essere archiviati?
**Se dispone di un assistente AI interno, chieda quali sono i documenti da cui attinge. Poi verifichi la freschezza di questi documenti.

Probabilmente scoprirà che i suoi documenti tecnicamente non scaduti presentano molti problemi che le date di scadenza non potranno mai individuare.

Le date di scadenza indicano se qualcuno ha controllato un documento di recente. La freschezza le dice se il documento è effettivamente sano in questo momento. Uno è un evento del calendario. L'altro è un segnale vivente.

Ha bisogno di entrambi. Ma se ha solo date di scadenza, vola alla cieca tra i punti di controllo.

Un documento non diventa obsoleto alla data di revisione. Diventa stantio nel momento in cui qualcosa cambia e nessuno se ne accorge. Il punteggio di freschezza se ne accorge.

Rasepi combina le date di scadenza obbligatorie con il monitoraggio continuo della freschezza. Ogni documento guadagna il suo punteggio di fiducia, o lo perde, in tempo reale. Nessuna attesa, nessun punto cieco, nessuna sorpresa al momento della revisione.

Guardi come funziona il punteggio di freschezza →

*Questa è la Parte 2 di una serie in due parti. Se non l'ha ancora letta, inizi con [Parte 1: La metrica che il suo team non tiene sotto controllo](/it/blog/perché la freschezza conta più di sempre/).

Freschezza dei contenuti, Parte 1: La metrica che il suo team non sta monitorando

2026-03-16T00:00:00Z

C'è un momento che ogni team di ingegneri ha vissuto. Qualcuno trova un documento sul wiki interno, segue le istruzioni e qualcosa si rompe. Manda un messaggio al canale: Nessuno lo sa. La persona che l'ha scritto se n'è andata otto mesi fa. Il documento dice che è stato modificato l'ultima volta nel 2024.

Questo è il problema della freschezza. E sta peggiorando.

Il vecchio contratto si sta rompendo

Per molto tempo, la documentazione ha avuto un contratto implicito: qualcuno la scrive, tutti si fidano e ogni tanto qualcuno la aggiorna. Forse. Questo contratto funzionava, a malapena, quando la documentazione veniva consumata solo da persone in grado di applicare il giudizio. Se una guida all'installazione sembrava un po' fuori luogo, un ingegnere senior si adattava al volo.

Ma quel mondo è finito. Oggi la sua documentazione non viene letta solo dagli esseri umani. Viene consumata da strumenti AI, chatbot interni, automazione dell'onboarding e sistemi di ricerca che trattano ogni parola come una verità equivalente. Un assistente AI non guarda un documento e pensa: "Questo sembra un po' datato", ma legge il testo, lo elabora come un dato di fatto e lo serve con piena fiducia.

**Documentazione obsoleta più AI equivale a risposte sbagliate e sicure in scala.

Cosa significa freschezza

La freschezza non è solo "quando è stato modificato l'ultima volta". Un documento potrebbe essere stato modificato ieri e fare ancora riferimento a un'API deprecata. La vera freschezza è un segnale composito:

Stato di revisione. Qualcuno ha confermato esplicitamente che questo documento è ancora accurato?
Salute dei link. Gli URL all'interno del documento si risolvono ancora?
Lettori. C'è qualcuno che lo usa davvero o è stato abbandonato?
Deriva contestuale. I documenti correlati sono cambiati mentre questo è rimasto invariato?
Allineamento della traduzione.** Se questo esiste in cinque lingue, sono tutte aggiornate?
Segnali della comunità.** I lettori hanno segnalato questo documento come obsoleto?

Ognuno di questi elementi le dice qualcosa di diverso. Insieme, le forniscono un punteggio di fiducia: un singolo numero che rappresenta quanta fiducia dovrebbe riporre in un contenuto in questo momento.

Perché questo è importante ora, in particolare

Tre cose sono confluite per rendere urgente la freschezza:

1. L'AI sta consumando la sua base di conoscenze

Sia che abbia implementato un sistema RAG interno, che utilizzi Copilot nel suo IDE o che abbia un assistente AI che risponde alle domande dei suoi documenti, la qualità del materiale di partenza determina direttamente la qualità dell'output. Garbage in, garbage out non è mai stato così letterale.

Quando uno sviluppatore chiede al suo assistente AI "come faccio a fare il deploy in staging?" e questo risponde utilizzando un runbook di due anni fa che fa riferimento a un'infrastruttura che nel frattempo è stata migrata, il costo non è solo una risposta sbagliata. È la perdita di fiducia nell'intero sistema.

2. I team sono più distribuiti che mai

Un team a Berlino, un altro a San Paolo, un terzo a Tokyo. Tutti leggono la stessa documentazione, spesso in lingue diverse. Quando la fonte inglese diventa obsoleta, anche tutte le traduzioni costruite su di essa diventano obsolete, ma nessuno se ne accorge perché le traduzioni vengono mantenute separatamente, se non del tutto.

3. La pressione della conformità e degli audit è in aumento

I settori regolamentati iniziano a chiedere: "Può dimostrare che questa documentazione era aggiornata al momento in cui è stata citata?". Se la sua risposta è "beh, probabilmente qualcuno l'ha controllata", non reggerà.

Come si presenta un approccio orientato alla freschezza

L'idea di base è semplice: ogni documento deve continuamente guadagnarsi il diritto di essere considerato attendibile.

Ciò significa che:

Date di revisione obbligatorie. Ogni documento riceve una data di scadenza al momento della sua creazione. Senza eccezioni. Quando arriva la data, il proprietario viene informato e il documento viene contrassegnato fino a quando qualcuno non lo riapprova esplicitamente.
**In background, il sistema controlla continuamente i link rotti, le tendenze dei lettori e i cambiamenti contestuali. Questi segnali confluiscono in un punteggio in tempo reale che si aggiorna senza che nessuno debba fare nulla.
**Questa è la chiave del meccanismo. Un documento con un punteggio elevato sale in cima ai risultati di ricerca e può essere utilizzato come fonte per le risposte dell'AI. Un documento con un punteggio basso scende nel ranking. Se scende al di sotto di una soglia, viene escluso completamente dalle risposte dell'AI.
Trasparenza. Tutti possono vedere perché un documento ha ottenuto il punteggio che ha ottenuto. Link rotti, revisione in ritardo, basso numero di lettori, i segnali sono visibili, non nascosti in un rapporto di backend che nessuno legge.

Il costo del non fare nulla

Ecco cosa succede quando non si tiene traccia della freschezza:

I nuovi assunti seguono documenti di onboarding obsoleti e trascorrono la prima settimana confusi.
Gli strumenti di intelligenza artificiale forniscono risposte sbagliate e nessuno capisce perché.
I documenti di conformità diventano silenziosamente obsoleti e creano rischi di audit.
Le traduzioni non sono sincronizzate e i team in regioni diverse lavorano con versioni diverse della realtà.
Gli ingegneri smettono di fidarsi completamente del wiki e tornano ai messaggi di Slack, che crea un proprio silos di conoscenza.

Il costo composto della documentazione obsoleta è enorme, ma è invisibile finché non si rompe qualcosa.

Un punto di partenza pratico

Non è necessario revisionare tutto in una volta. Inizi con questi:

Audit dei suoi 20 documenti più letti. Quando sono stati rivisti l'ultima volta? I link sono ancora validi? Il contenuto è ancora accurato?
**Anche se non fa altro, inserire una data di "revisione entro" su ogni documento crea responsabilità.
**Se dispone di un assistente AI interno, osservi quali sono i documenti da cui attinge. Questi documenti sono aggiornati?
Rendere visibile la freschezza. Metta il punteggio dove le persone possono vederlo, accanto al titolo del documento, nei risultati di ricerca, nella barra laterale. La visibilità crea una pressione a mantenerlo.

La freschezza della documentazione non è una caratteristica. È un cambiamento fondamentale nel modo in cui pensiamo alla conoscenza organizzativa. In un mondo in cui gli strumenti di intelligenza artificiale consumano e ridistribuiscono i documenti su scala, la domanda non è se può permettersi di preoccuparsi della freschezza. È se può permettersi di non farlo.

Ogni documento dovrebbe dimostrare di essere ancora degno di fiducia. Non una volta. Continuamente.

Questo è ciò che stiamo costruendo in Rasepi. Una piattaforma in cui la freschezza non è un ripensamento. È la base su cui si fonda tutto il resto. Applicazione delle recensioni, punteggio di salute in tempo reale, ricerca ponderata sulla freschezza e risposte AI che utilizzano solo fonti di cui ci si può fidare.

Guardi come funziona →

Questa è la Parte 1 di una serie in due parti. Nella Parte 2: Oltre le date di scadenza, esploriamo come il monitoraggio continuo della freschezza colma le lacune che le date di revisione lasciano aperte.

Insegnare alla sua AI a ignorare la documentazione obsoleta

2026-03-12T00:00:00Z

Ecco cosa succede quando si implementa un assistente AI in cima alla sua base di conoscenza interna:

Un nuovo ingegnere chiede: "Come faccio a configurare l'ambiente di staging?".

L'AI cerca nella sua documentazione, trova tre documenti pertinenti, sintetizza una risposta e la presenta con fiducia. L'ingegnere segue le istruzioni. I primi due passaggi funzionano. Il terzo passo fa riferimento a uno strumento CLI che è stato deprecato sei mesi fa. Il quarto passo descrive una configurazione dell'infrastruttura che è stata sostituita durante una migrazione che non è stata documentata.

Il tecnico è bloccato. Invia un messaggio al canale del team. Qualcuno dice: "Oh, quel documento è molto vecchio". L'AI non lo sapeva. Non può saperlo. Ha semplicemente recuperato tutto ciò che ha trovato e lo ha presentato come verità.

**Questo è il comportamento predefinito di ogni sistema RAG, di ogni strumento di ricerca AI e di ogni assistente LLM che lei abbia mai usato per i documenti interni. Recuperano tutto. Non fanno discriminazioni. Non sanno distinguere le cose fresche da quelle stantie.

E sta distruggendo la fiducia negli strumenti di AI più velocemente di quanto questi possano costruirla.

Perché gli assistenti AI sono ciechi alla qualità

I grandi modelli linguistici e i sistemi di retrieval-augmented generation (RAG) funzionano trovando un testo semanticamente rilevante per una query, quindi utilizzando quel testo per generare una risposta. La corrispondenza di pertinenza è solitamente eccellente. La ricerca vettoriale e le incorporazioni sono davvero ottime per trovare i contenuti che si riferiscono a una domanda.

Ma la pertinenza non è la stessa cosa dell'affidabilità.

Un documento scritto nel 2023 sul suo processo di implementazione di Kubernetes è altamente rilevante per la domanda "come faccio a implementare in produzione?". È anche completamente sbagliato se è migrato a una piattaforma diversa nel 2024. L'AI vede un testo rilevante. Non vede un documento non aggiornato da 18 mesi, con link non funzionanti e zero lettori.

La maggior parte dei sistemi di intelligenza artificiale ha esattamente un segnale di ranking: la somiglianza semantica con la query. Tutto qui. Non controllano:

Quando è stato rivisto l'ultima volta questo documento?
I link al suo interno sono ancora validi?
C'è qualcuno che sta leggendo questo documento?
Il contenuto è stato segnalato dai lettori come obsoleto?
Si tratta di una bozza, di una pagina archiviata o di un documento attuale?
Se esiste in più lingue, le traduzioni sono aggiornate?

Senza questi segnali, l'AI esegue una corrispondenza di parole chiave con passaggi aggiuntivi. Una corrispondenza di parole chiave impressionante, sì, ma fondamentalmente incapace di dirle se la risposta che le sta dando è basata su contenuti di cui si può fidare.

Il problema della fiducia

Questo non sarebbe così pericoloso se gli strumenti di AI presentassero risposte incerte con avvertenze appropriate. Ma non lo fanno. Non è così che funzionano i LLM. Generano un testo fluente e sicuro, indipendentemente dal fatto che il materiale di partenza sia attuale o antico.

Un umano che legge un articolo wiki potrebbe notare che sembra datato. Il layout della pagina è vecchio. Gli screenshot mostrano un'interfaccia utente che non esiste più. C'è un commento in fondo che dice "questo è obsoleto". Un umano può applicare un giudizio.

Un'intelligenza artificiale non può farlo. Legge il testo, lo elabora come equivalente a qualsiasi altro testo e genera una risposta che sembra autorevole. L'utente, soprattutto un nuovo assunto che non conosce il processo attuale, non ha motivo di dubitare.

Più l'IA suona sicura, più il materiale di origine stantio viene danneggiato.

Ciò di cui l'AI ha effettivamente bisogno

Affinché un assistente AI fornisca risposte affidabili dalla sua base di conoscenza, ha bisogno di qualcosa di più del testo e degli embeddings. Ha bisogno di metadati che le indichino quali documenti vale la pena utilizzare come fonti. In particolare:

1. Punteggio di freschezza

Un segnale numerico che rappresenta quanto è sano un documento in questo momento. Non quando è stato modificato l'ultima volta, che è solo un input. Un vero punteggio di freschezza combina lo stato delle recensioni, la salute dei link, la readership, l'allineamento della traduzione e la deriva contestuale in un unico numero.

Quando un documento ottiene un punteggio superiore ad una soglia (ad esempio, 70 su 100), è idoneo ad essere utilizzato come fonte per le risposte dell'AI. Al di sotto di tale soglia, viene escluso. Non ci sono eccezioni.

Questo unico meccanismo elimina la classe più pericolosa di errori di AI: risposte sbagliate e sicure basate su fonti obsolete.

2. Stato di scadenza

Questo documento è attualmente nella sua finestra di revisione o è scaduto senza essere riapprovato? Un documento scaduto dovrebbe essere fortemente deprivato o escluso del tutto, indipendentemente dalla rilevanza del suo contenuto per la query.

In Rasepi, i documenti scaduti vengono segnalati e il loro punteggio di freschezza diminuisce automaticamente. Un sistema AI che interroga la base di conoscenza può vedere questo stato e agire di conseguenza.

3. Etichette di classificazione

Non tutti i documenti servono allo stesso scopo. Una bozza non dovrebbe essere utilizzata come fonte. Un documento archiviato non dovrebbe apparire nelle risposte dell'AI. Un documento esclusivamente interno non dovrebbe apparire nelle query degli strumenti esterni.

Le etichette di classificazione forniscono all'AI un contesto sul tipo di documento che sta esaminando:

Pubblicato. Attuale, approvato, sicuro da usare
Draft. Lavoro in corso, non deve essere citato
In corso di revisione.** Scadenza attivata, in attesa di riapprovazione
Archiviato.** Non più attivo, conservato solo per riferimento
Interno / Esterno. Controlli l'ambito di visibilità

Quando un assistente AI elabora una query, può filtrare in base alla classificazione prima ancora di esaminare la rilevanza del contenuto. Una bozza di documento che corrisponde perfettamente alla query non dovrebbe mai essere servita come risposta.

4. Segnali a livello di lingua

Se la sua base di conoscenza è multilingue, l'AI deve sapere se la versione da cui attinge è attuale. Una traduzione francese che è tre mesi indietro rispetto alla fonte inglese è tecnicamente rilevante in francese, ma le informazioni potrebbero essere obsolete.

Rasepi tiene traccia della freschezza a livello di lingua. Ogni traduzione ha il proprio punteggio in base al fatto che i blocchi di origine sono cambiati dall'ultimo aggiornamento della traduzione. Un'IA che interroga la base di conoscenza francese può vedere che la versione francese di un documento è obsoleta e o:

Ritornare alla fonte inglese (che è aggiornata).
Includere un'avvertenza che la versione francese potrebbe essere obsoleta.
Escludere completamente il documento

5. Segnali del lettore

Se più lettori hanno segnalato un documento come obsoleto, questo segnale dovrebbe ridurre il peso del documento nelle risposte dell'AI. I segnali di qualità raccolti dalla folla sono rumorosi, ma sono preziosi, soprattutto se combinati con altre metriche di freschezza.

Come funziona in pratica

Vediamo cosa succede quando un assistente AI interroga una base di conoscenza Rasepi:

Domanda: "Qual è il nostro processo per gestire un incidente P1 alle 2 del mattino?".

Fase 1: Recupero con filtraggio. Il sistema cerca documenti semanticamente rilevanti. Prima di classificare, filtra:

Documenti con punteggio di freschezza inferiore alla soglia
Documenti scaduti che non sono stati riapprovati
Bozze e contenuti archiviati
Documenti la cui versione linguistica è obsoleta (se la query è in una lingua non primaria).

Fase 2: Classifica ponderata per la freschezza. Tra i documenti rimanenti, quelli con punteggi di freschezza più elevati si posizionano più in alto. Un documento con punteggio 94 supera uno con punteggio 72, anche se il documento con punteggio 72 ha una somiglianza semantica leggermente superiore.

Fase 3: generazione della risposta. L'AI genera una risposta dalle fonti filtrate e classificate per freschezza. Ogni fonte è citata con il suo punteggio di freschezza visibile.

**Se la migliore fonte disponibile ha un punteggio di freschezza borderline, l'AI include un'avvertenza: _"Nota: la fonte principale per questa risposta è stata rivista l'ultima volta 60 giorni fa. Potrebbe voler verificare con il team".

Confrontiamo questo con il comportamento predefinito: trovare il testo pertinente, generare una risposta sicura, sperare per il meglio.

Cosa succede quando non lo fa

Le conseguenze dei sistemi di AI che operano su basi di conoscenza non filtrate sono prevedibili e costose:

**Il caso d'uso più comune dell'AI per i documenti interni è l'onboarding. I nuovi assunti, per definizione, non sanno cosa è attuale e cosa è obsoleto. Si fidano dell'AI. L'AI si fida di tutto. I documenti obsoleti vengono serviti con fiducia.

**Se l'assistente AI fornisce indicazioni sui processi normativi utilizzando documenti obsoleti, il consiglio potrebbe non solo essere sbagliato, ma anche non conforme. "L'AI mi ha detto di farlo" non regge in un audit.

**Ogni volta che l'AI dà una risposta sbagliata, gli utenti si fidano un po' meno. Dopo tre o quattro esperienze negative, smettono di usarla. L'investimento in strumenti di IA non offre alcun valore perché il contenuto sottostante non era affidabile.

**Quando le persone perdono fiducia nella base di conoscenza ufficiale (e nell'AI costruita su di essa), ne creano una propria: Messaggi Slack, note personali, conoscenze tribali condivise durante le riunioni. La frammentazione che il wiki avrebbe dovuto evitare avviene comunque, ma in modo diverso.

La soluzione è alla fonte, non al modello

C'è la tentazione di risolvere questo problema a livello di intelligenza artificiale: suggerimenti migliori, pipeline RAG più sofisticate, modelli perfezionati che possano in qualche modo rilevare la stasi dal solo testo. Questo è l'approccio sbagliato.

La soluzione è alla fonte. Se i suoi documenti contengono metadati ricchi e accurati sul loro stato attuale (punteggio di freschezza, stato di scadenza, classificazione, allineamento linguistico, segnali del lettore), qualsiasi sistema di intelligenza artificiale può utilizzare tali metadati per prendere decisioni migliori. Non le serve un modello più intelligente. Ha bisogno di documenti più intelligenti.

Questo è ciò che offre Rasepi:

Ogni documento ha un punteggio di freschezza in tempo reale che si aggiorna continuamente in base alla salute dei link, ai lettori, allo stato delle recensioni e altro ancora.
Ogni documento ha una data di scadenza** che attiva la revisione al suo arrivo.
Ogni documento ha una classificazione** (pubblicato, in bozza, in revisione, archiviato).
Ogni versione linguistica ha un proprio segnale di freschezza**, per cui le traduzioni stantie vengono rilevate in modo indipendente.
I flag del lettore e il tracciamento dei riferimenti incrociati** aggiungono ulteriori segnali di qualità.

Quando un sistema AI interroga la base di conoscenza di Rasepi, tutti questi metadati sono disponibili. L'AI non deve indovinare se un documento è affidabile. Il documento glielo dice.

Un punto di partenza pratico

Se oggi ha un assistente AI in esecuzione sulla sua base di conoscenza, può iniziare a valutare il problema in 30 minuti:

Porre al suo assistente AI 10 domande di cui conosce la risposta. Notare quali risposte utilizzano fonti obsolete. Probabilmente scoprirà che almeno 2-3 su 10 si basano su contenuti obsoleti.
**Per ogni risposta fornita dall'AI, guardi il documento di origine. Quando è stato rivisto l'ultima volta? I link sono validi? Si fiderebbe se lo leggesse personalmente?
**Trova il suo documento più vecchio e trascurato che appare ancora nei risultati di ricerca. Ponga all'AI una domanda che lo faccia emergere. L'AI lo usa? Quasi certamente sì.
Stimare l'impatto. Quante query al giorno gestisce il suo assistente AI? Se il 20-30% delle risposte si basa su contenuti obsoleti, qual è il costo in termini di tempo sprecato, decisioni sbagliate e perdita di fiducia?

Gli assistenti AI sono validi solo quanto il contenuto su cui sono costruiti. Al momento, la maggior parte di essi considera ogni documento della sua base di conoscenza come ugualmente valido. Recuperano tutto, il documento che è stato rivisto ieri e quello che nessuno ha toccato in due anni, e lo presentano con la stessa fiducia.

Questo non è un problema di modello. È un problema di qualità dei dati. La soluzione è semplice: fornire ai documenti dei metadati che indichino agli strumenti di intelligenza artificiale di cosa fidarsi.

**Il suo assistente AI non dovrebbe essere sicuro di una risposta ottenuta da un documento che nessuno ha esaminato in 18 mesi. Con i segnali giusti, non lo farà.

Rasepi fa sì che ogni documento abbia il suo punteggio di fiducia: freschezza, stato di scadenza, classificazione, allineamento linguistico. Gli strumenti di AI interrogano la base di conoscenza e ottengono non solo il contenuto, ma anche il contesto. Le fonti affidabili emergono. Quelle obsolete no. Ecco come dovrebbe funzionare la documentazione alimentata dall'AI.

Guardi come funziona Rasepi con gli strumenti di AI →

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 scopa in /api/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, 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 ogni 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 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 l'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.