Dalla pagina al modulo: contenuti fluidi, strutturati e modulari

Benvenute, nuove persone arrivate! Vi accolgo con alcuni link.

• Potete scaricare l’ebook con le interviste sulla scrittura del 2023: avete a disposizione sia l’epub che il pdf.
• La serie di interviste del 2024 riguarda la lettura: quella a Luigi Civalleri sulla traduzione è fresca fresca.

La settimana scorsa ho concluso il corso di Accessibilità, Usabilità e User Experience nella comunicazione tecnica che ho tenuto per COM&TEC. L’aspetto migliore della formazione è che, quando funziona, impara qualcosa anche chi insegna: tra le cose su cui ho riflettuto ce ne sono alcune che possono interessare anche voi. Un pistolotto non indifferente, vi avviso.

Sulle parole: strutturate e modulari

Che cos’è la documentazione tecnica? Pensa, per esempio, ai manuali di macchinari per l’industria o la sanità: quali procedure richiede l’uso del mammografo con tomosintesi? Quali sono le procedure di sicurezza da adottare per le macchine per la lavorazione del ferro per cemento armato? Cose del genere. Da comuni mortali potremmo pensare al manuale d’uso della nostra automobile: la differenza sostanziale sta nel fatto che la documentazione tecnica non è destinata ai consumatori, ma agli operatori specializzati che useranno attrezzature, macchinari, software, eccetera.

Va da sé che si tratti di un ambito molto regolamentato: esiste un vero e proprio sistema di norme e standard di riferimento per questo tipo di documenti, così da garantire che le informazioni siano non solo corrette, ma anche sicure, accessibili e utili per chi le riceverà. Le norme hanno valore legale, gli standard traducono i requisiti legali in linee guida operative. Comprendere questo sistema è fondamentale, perché influenza ogni aspetto del lavoro, dalla pianificazione alla consegna del documento finale.

I requisiti hanno un impatto diretto sulla qualità della documentazione e sull’esperienza di chi la usa:

• garantiscono che le informazioni di sicurezza siano complete e chiare;
• rendono i documenti accessibili a un pubblico più ampio;
• permettono di creare contenuti più facili da aggiornare e manutenere;
• facilitano la traduzione in altre lingue;
• riducono il rischio di errori e incomprensioni.

Norme e standard sono un sistema perché sono coerenti tra loro e convergono su più punti. In generale, per esempio, riguardo la prospettiva da adottare, le persone sono senza dubbio in primo piano.

• L’attenzione è centrata sulle persone: la documentazione deve essere progettata per soddisfare le esigenze delle persone, fornendo informazioni chiare, concise e facilmente accessibili.
• Chiarezza e comprensibilità devono essere garantite: il linguaggio deve essere semplice e diretto, ed evitare tecnicismi.
• Le informazioni devono essere strutturate in modo logico e coerente: la documentazione deve essere organizzata in modo da facilitare la navigazione e la ricerca delle informazioni.

Anche per quanto riguarda la qualità delle informazioni nella documentazione, emerge una cornice solida e coerente.

• Chiarezza e concisione: le informazioni devono essere presentate in modo chiaro, conciso e facilmente comprensibile.
• Completezza: la documentazione deve fornire tutte le informazioni necessarie per comprendere e utilizzare il prodotto o il servizio. Per esempio, deve includere tutte le funzionalità del prodotto, descrivere i possibili errori e fornire soluzioni per risolverli.
• Coerenza: il linguaggio, lo stile e la terminologia devono essere coerenti in tutta la documentazione. Si tratta, per esempio, di utilizzare lo stesso stile di scrittura, la stessa terminologia e lo stesso formato per le intestazioni, i paragrafi e le liste.
• Accessibilità: la documentazione deve essere accessibile per tutti, comprese le persone con disabilità.
• Modularità: i contenuti devono essere organizzati in moduli indipendenti e riutilizzabili, per facilitare la manutenzione e l’aggiornamento.

Un approccio strutturato

La documentazione tecnica richiede quindi un approccio sistematico e strutturato. Non si tratta solo di scrivere dei manuali, ma di gestire informazioni complesse che devono essere accurate, coerenti, aggiornabili e riutilizzabili. Molti strumenti tecnologici vengono in soccorso, naturalmente, ma alla base dell’organizzazione della scrittura ci sono i concetti di contenuti strutturati e modulari.

Strutturare i contenuti significa organizzare le informazioni in modo logico e gerarchico, utilizzando elementi standard come titoli, paragrafi, elenchi e tabelle. I vantaggi sono numerosi: maggiore chiarezza, coerenza, concisione e facilità di navigazione.

I contenuti modulari suddividono l’informazione in unità indipendenti e riutilizzabili, chiamate moduli. In questo modo i contenuti sono flessibili, perché possono essere combinati e riorganizzati in base alle esigenze, e sono più semplici da aggiornare, perché si può modificare un singolo modulo senza dover rivedere l’intero documento.

Vediamo due esempi¹ e poi commentiamoli.

Esempio 1: né strutturato né modulare

Il sistema di controllo della temperatura TC-100 gestisce il riscaldamento del reattore principale. Per avviare il sistema, accendere l’interruttore principale sul pannello A e attendere l’inizializzazione del display. Verificare che la temperatura iniziale sia compresa tra 15°C e 25°C. Impostare la temperatura target usando i pulsanti + e - sul pannello. Il sistema accetterà solo valori tra 50°C e 200°C. Durante il riscaldamento, monitorare la pressione sul manometro P-100. Se la pressione supera 2.5 bar, interrompere immediatamente il processo premendo il pulsante rosso di emergenza. Per la manutenzione ordinaria, verificare mensilmente la calibrazione dei sensori di temperatura e pressione. Pulire i filtri dell’aria ogni tre mesi. Sostituire le guarnizioni del sistema di raffreddamento annualmente.

Esempio 2: strutturato e modulare

Panoramica del sistema TC-100

Il sistema di controllo della temperatura TC-100 gestisce il riscaldamento del reattore principale. Opera in un intervallo di temperatura tra 50°C e 200°C, con sistemi di sicurezza integrati per il monitoraggio della pressione.

Procedura di avvio

1. Accendere l’interruttore principale sul pannello A
2. Attendere l’inizializzazione del display
3. Verificare temperatura iniziale (15-25°C)
4. Impostare temperatura target con i pulsanti + e -

Monitoraggio e sicurezza

Durante l’operazione, monitorare la pressione sul manometro P-100. Limite massimo: 2.5 bar.

Procedura di emergenza

Premere il pulsante rosso se la pressione supera il limite.

Piano di manutenzione

• Calibrazione sensori: mensile
• Pulizia filtri aria: trimestrale
• Sostituzione guarnizioni: annuale

Commento

Nel primo esempio il testo non ha nessuna struttura: non c’è gerarchia, non c’è ordine logico nella sequenza dei contenuti, non ci sono appigli per la comprensione.

Nel secondo esempio² il testo è strutturato: ciascun argomento ha un titolo, dove serve ci sono elenchi ordinati o non ordinati. Le unità di testo sono indipendenti: nel linguaggio usato non ci sono parole che suggeriscono relazioni con quanto precede o segue, sono leggibili in modo autonomo (in riferimento al sistema TC-100).

La granularità dell’informazione

La sfida centrale nei contenuti modulari è trovare il giusto livello di granularità. I moduli devono essere abbastanza piccoli da essere flessibili e riutilizzabili, ma abbastanza grandi da mantenere un significato autonomo. È un equilibrio delicato che richiede una profonda comprensione sia del contenuto tecnico che delle esigenze delle persone.

La granularità ottimale crea unità di informazione che sono:

• autonome ma interconnesse;
• focalizzate su un singolo obiettivo;
• abbastanza complete da essere significative;
• abbastanza specifiche da essere riutilizzabili.

Questo equilibrio permette di mantenere i vantaggi della modularità senza perdere la coerenza e il contesto necessari per una documentazione efficace.

La modularità, quando ben implementata, supporta naturalmente l’accessibilità. La struttura chiara e la granularità appropriata permettono una navigazione più efficace per tutti, incluse le persone che utilizzano tecnologie assistive.

Il sistema di relazioni

In un sistema modulare, le relazioni tra i contenuti diventano cruciali quanto i contenuti stessi. Le relazioni devono essere esplicite e gestibili, permettendo di mantenere l’integrità dell’informazione anche quando i singoli moduli vengono aggiornati o riutilizzati. È necessario un sistema robusto di metadati e riferimenti che permetta di tracciare le dipendenze tra i moduli e di assemblarli in modo coerente.

I metadati sono informazioni aggiuntive che descrivono il contenuto dei moduli. Possono includere parole chiave, categorie, autori, date di creazione e aggiornamento. I metadati facilitano la ricerca e il recupero delle informazioni, soprattutto in grandi archivi di documentazione: sono come etichette che applichiamo ai moduli e ci aiutano a classificarli e trovarli facilmente quando ne abbiamo bisogno.

Il contenuto e la forma

La chiave dell’approccio modulare ai contenuti sta nella chiara separazione tra il contenuto e la sua presentazione: è questa che permette la flessibilità nell’uso e nel riutilizzo delle informazioni.

Per fare questo abbiamo a disposizione i linguaggi di markup semantico: si tratta di linguaggi in grado di descrivere il significato e la struttura di un documento, anzi che il suo aspetto visivo. Il markup semantico aiuta a identificare il ruolo di ciascun elemento del documento (per esempio, un titolo, un paragrafo, una tabella), e consente a software e strumenti di interpretarli e utilizzarli in modo più intelligente. Il più noto è forse l’HTML, grazie al quale stai leggendo anche questo testo.

Proprio come il linguaggio che usiamo per parlare, anche i linguaggi di markup hanno una sintassi e delle regole per strutturare e rappresentare le informazioni. Questo garantisce che gli elementi, gli attributi e la gerarchia siano ben chiari nella struttura, così i documenti sono coerenti e facili da interpretare, sia dalle persone sia dai software. Le regole di base per i linguaggi di markup sono in genere quelle dell’XML, da cui derivano delle versioni specializzate in base all’oggetto che vogliono descrivere.

• DocBook: usato principalmente per la documentazione tecnica, è ideale per manuali, guide e libri. La sua struttura logica e la capacità di separare contenuto e presentazione lo rendono adatto alla pubblicazione multicanale, consentendo di generare facilmente versioni per diversi formati (ePub, PDF, HTML)
• DITA: è perfetto per creare e aggiornare grandi quantità di documentazione tecnica. Supporta la modularità e il riutilizzo dei contenuti.
• MathML: creato per la notazione matematica.
• MusicXML: per la notazione musicale digitale.
• SVG: descrive grafica vettoriale bidimensionale.

Quanto abbiamo viaggiato, doc?

Quando mi occupavo di produzione di libri digitali masticavo linguaggi di markup anche a colazione³. Il trauma dell’editoria per il passaggio dal layout fisso della carta/PDF al formato fluido dell’ebook era palpabile: il problema da risolvere in produzione era ottenere l’uno e l’altro con una sola lavorazione del testo.

Anche per la documentazione tecnica rimane un tema cruciale: la possibilità di avere una sorgente di contenuti fluidi, da incanalare in diversi tipi di formato e in diversi contesti di lettura a seconda delle esigenze, con il minimo sforzo di adattamento a posteriori e con il massimo controllo su sicurezza, esattezza e completezza delle informazioni.

Riferimenti

Esempi di normative europee e nazionali

• Direttiva Macchine 2006/42/CE: non dice solo come dev’essere costruita una macchina, ma anche come deve essere documentato il suo utilizzo sicuro.
• Codice dell’Amministrazione Digitale: stabilisce come devono essere realizzati i documenti digitali nella pubblica amministrazione, specie riguardo l’accessibilità.

Esempi di standard e Linee guida

• ISO 9241-210: Human-centred design for interactive systems, dedicato alla progettazione centrata sull’utente.
• ISO 82079-1: Preparation of information for use (instructions for use) of products, che si concentra specificamente sulla preparazione delle istruzioni per l’uso.
• ISO 24495-1: Plain Language, che riguarda l’uso del linguaggio chiaro.
• WCAG (Web Content Accessibility Guidelines), che danno indicazioni dettagliate su come rendere i contenuti digitali accessibili a tutti.
• Italiano Tecnico Semplificato® (ITS), standardizzazione linguistica per la migliore Accessibilità, Usabilità e User Experience nella Comunicazione e Documentazione Tecnica.

Esercizi

Anche gli esercizi? No, dai, questa volta no, abbiamo proprio esagerato.

Un libro

Devo trovare io le parole per presentare Rayuela, di Cortázar? Mi sento in imbarazzo. I 155 capitoli del romanzo si possono leggere in modo non lineare, e Cortázar stesso suggerisce due percorsi di lettura nella Tavola di orientamento, che puoi sbirciare nell’estratto dell’ebook. Rayuela è un romanzo sperimentale, strutturato come una serie di inizi di libri diversi, interrotti e interconnessi tra loro: «un gioco di scatole cinesi che crea un effetto metanarrativo, in cui chi legge diventa parte attiva del processo di creazione del testo». O almeno così dice Wikipedia. Te l’ho detto che mi sentivo in imbarazzo, a presentarlo io.

Tre link

• Una raccolta di link per riassumere cosa abbiamo imparato in tema di LLMs nel 2024.
• The Role Of Illustration Style In Visual Storytelling
• Sentient Design: AI and the Next Chapter of UX (sarà una nuova buzz word? Chissà.)