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.