La sostenibilità nella Documentazione Tecnica
Una documentazione tecnica non dovrebbe essere soltanto corretta nel momento in cui viene consegnata.
Dovrebbe poter essere creata, tradotta, pubblicata, utilizzata, aggiornata e mantenuta nel tempo con un impiego di risorse proporzionato al valore dell’informazione che fornisce.
È questo che in AP Publishing intendiamo per sostenibilità della documentazione tecnica.
Un manuale può essere perfettamente realizzato oggi e diventare difficile e costoso da gestire dopo pochi anni se i suoi contenuti sono duplicati, poco strutturati, difficili da aggiornare, incoerenti dal punto di vista terminologico o inutilmente estesi.
La sostenibilità della documentazione non riguarda quindi soltanto il documento finale.
Riguarda l’intero ciclo di vita dell’informazione:
PROGETTARE → SCRIVERE → RIUSARE → TRADURRE → PUBBLICARE → DISTRIBUIRE → AGGIORNARE → RIUTILIZZARE
Che cos’è la sostenibilità nella documentazione tecnica?
Per AP Publishing una documentazione tecnica è sostenibile quando può essere creata, tradotta, pubblicata, utilizzata, aggiornata e mantenuta nel tempo con un impiego di risorse proporzionato al valore dell’informazione che fornisce.
Questo significa progettare un sistema documentale che sia:
- ripetibile;
- semplice da gestire;
- efficace per l’utilizzatore;
- modificabile;
- riutilizzabile;
- applicabile, quando possibile, a prodotti e varianti differenti;
- facilmente traducibile;
- pubblicabile sui diversi canali necessari;
- mantenibile durante il ciclo di vita del prodotto.
Ma soprattutto deve essere utile.
Perché un’informazione inutile rimane inutile anche quando è perfettamente scritta, impaginata e tradotta.
Tre dimensioni della sostenibilità documentale
Possiamo considerare la sostenibilità della documentazione tecnica attraverso tre dimensioni strettamente collegate.
1. Sostenibilità del contenuto
Significa produrre informazioni corrette, comprensibili, coerenti, riutilizzabili e realmente necessarie al destinatario.
Ogni contenuto dovrebbe avere una funzione.
Deve permettere all’utilizzatore di:
- comprendere;
- decidere;
- eseguire un’attività;
- evitare un errore;
- gestire un rischio;
- individuare un componente;
- trovare un’informazione.
Quando una frase non svolge nessuna di queste funzioni, dovremmo almeno chiederci perché la stiamo mantenendo.
2. Sostenibilità del processo
Una documentazione può contenere ottime informazioni ed essere prodotta attraverso un processo estremamente inefficiente.
- Copie manuali.
- Contenuti duplicati.
- Correzioni ripetute sugli stessi testi.
- Terminologia non controllata.
- Traduzioni di frasi già tradotte.
- Impaginazioni ricostruite per ogni pubblicazione.
- Informazioni che devono essere aggiornate separatamente in più documenti.
La sostenibilità riguarda quindi anche come produciamo e gestiamo l’informazione.
Un processo sostenibile dovrebbe ridurre le attività prive di valore e favorire standardizzazione, automazione e riuso quando questi portano un beneficio reale.
3. Sostenibilità nel ciclo di vita
Un prodotto può rimanere sul mercato per anni.
Una macchina o un impianto può rimanere in servizio per decenni.
Nel frattempo cambiano componenti, configurazioni, ricambi, procedure, software, requisiti, mercati e informazioni destinate agli utilizzatori.
La domanda non dovrebbe quindi essere soltanto:
“Quanto ci costa produrre questo manuale?”
ma anche:
“Quanto ci costerà mantenerlo corretto nei prossimi anni?”
È questa seconda domanda che cambia profondamente il modo di progettare la documentazione tecnica.
Il costo di un contenuto non finisce quando lo abbiamo scritto
Ogni frase introdotta nella documentazione genera un costo.
Deve essere:
scritta → revisionata → approvata → impaginata → tradotta → pubblicata → aggiornata → verificata nel tempo.
Se quella frase viene pubblicata in dieci lingue, non abbiamo più una sola frase da gestire.
Se compare in cinque manuali differenti, il problema si moltiplica.
Se viene modificata frequentemente durante il ciclo di vita del prodotto, dovrà essere nuovamente verificata, tradotta e pubblicata.
Possiamo rappresentare provocatoriamente il problema così:
contenuto inutile × lingue × varianti × revisioni × anni di vita = costo documentale
Non è una formula contabile.
È però un buon modo per ricordare che ogni informazione che decidiamo di creare dovrà successivamente essere mantenuta.
Il minimalismo è uno dei principi della documentazione sostenibile
Per questo il minimalismo nella redazione tecnica è strettamente collegato alla sostenibilità.
Minimalismo non significa scrivere poco.
Significa fornire tutte e sole le informazioni necessarie al destinatario.
La IEC/IEEE 82079-1 considera il minimalismo tra i principi relativi alla qualità delle informazioni per l’uso, insieme a completezza, correttezza, concisione, coerenza, comprensibilità e accessibilità.
Completezza e minimalismo non sono quindi contrari.
Una documentazione sostenibile deve fornire tutte le informazioni necessarie, evitando contemporaneamente contenuti che non producono valore per l’utilizzatore.
Ogni contenuto superfluo che eliminiamo è un contenuto che non dovremo:
revisionare → tradurre → pubblicare → aggiornare → mantenere.
Il riuso rende sostenibile la produzione dell’informazione
Un altro principio fondamentale è il riuso.
Supponiamo di avere dieci modelli di una macchina che condividono la stessa procedura di manutenzione.
Possiamo scrivere dieci procedure.
Oppure possiamo progettare un contenuto riutilizzabile.
Nel primo caso una modifica tecnica potrebbe richiedere dieci interventi.
Nel secondo possiamo intervenire sulla fonte comune e gestire la variazione attraverso un processo controllato.
La relazione è semplice:
meno duplicazioni → meno punti da controllare → meno possibilità di incoerenza → minore costo di mantenimento.
Questo è uno dei motivi per cui modularità, contenuti strutturati e sistemi CCMS possono diventare strumenti importanti.
Ma il software, da solo, non rende sostenibile la documentazione.
Se inseriamo contenuti mal progettati in un CCMS, avremo semplicemente contenuti mal progettati gestiti da un software più sofisticato.
Prima dello strumento viene l’architettura dell’informazione.
Una guida di stile riduce il costo della variabilità
La sostenibilità riguarda anche il modo in cui scriviamo.
Se tre redattori descrivono la stessa operazione in tre modi differenti, otteniamo tre contenuti da revisionare e potenzialmente tre nuovi segmenti da tradurre.
Una guida di stile serve quindi anche a limitare la variabilità linguistica priva di funzione.
Definire regole condivise per:
- struttura delle frasi;
- procedure;
- terminologia;
- avvertenze;
- titoli;
- unità di misura;
- numeri;
- immagini;
- riferimenti;
permette di rendere il processo più prevedibile e ripetibile.
La standardizzazione non deve rendere il testo artificiale.
Deve evitare che ogni redattore debba reinventare ogni volta una soluzione già disponibile.
Prima di riscrivere, cerchiamo se abbiamo già scritto
Lo stesso principio può essere applicato alle Translation Memory.
Una memoria di traduzione non contiene soltanto traduzioni.
Contiene anche migliaia di frasi sorgente che l’organizzazione ha già scritto, revisionato e utilizzato.
Se queste frasi sono state costruite applicando una guida di stile aziendale, possono diventare un patrimonio riutilizzabile durante la produzione di nuovi contenuti.
Prima di scrivere nuovamente:
Premere il pulsante START per avviare la macchina.
possiamo verificare se abbiamo già una formulazione approvata per esprimere quel concetto.
Il processo diventa:
CERCA → VERIFICA → RIUTILIZZA
È uno dei principi alla base di Translations Base, la soluzione AP Publishing che rende consultabili Translation Memory e database terminologici anche al di fuori del processo di traduzione.
La tecnologia è però secondaria rispetto al principio:
non ricreare inutilmente ciò che l’organizzazione ha già prodotto e validato.
Anche la terminologia deve essere sostenibile
Lo stesso componente non dovrebbe cambiare nome ogni volta che cambia redattore, reparto o documento, a meno che non esista una ragione precisa.
pulsante
tasto
comando
possono sembrare semplici alternative linguistiche.
Nella documentazione tecnica possono invece generare ambiguità, revisioni, nuove traduzioni e incoerenze.
Un Termbase permette di governare queste decisioni definendo termini validati, sinonimi, termini obsoleti e termini proibiti nei diversi contesti.
La sostenibilità terminologica può quindi essere rappresentata così:
concetto → contesto → termine approvato → riuso
Non significa eliminare ogni variante.
Significa eliminare le varianti non governate.
Una buona documentazione sorgente rende più sostenibile anche la traduzione
Quando un prodotto viene commercializzato in molti Paesi, la sostenibilità del sorgente diventa ancora più importante.
Ogni parola inutile deve essere tradotta.
Ogni nuova variante linguistica deve essere valutata.
Ogni incoerenza terminologica può propagarsi nelle diverse lingue.
Ogni contenuto duplicato può diventare un ulteriore elemento da mantenere.
Una documentazione sorgente controllata permette invece di aumentare il riuso delle Translation Memory e di ridurre la quantità di contenuto realmente nuovo.
Il principio diventa:
contenuto sorgente coerente → maggiore riuso → meno contenuto nuovo → meno traduzione → meno contenuto da mantenere
Non dobbiamo però scrivere male o impoverire il contenuto soltanto per ottenere maggiori corrispondenze nella Translation Memory.
La priorità rimane sempre:
correttezza → comprensibilità → utilità → sicurezza.
La sostenibilità viene costruita intorno a questi requisiti, non al loro posto.
La conoscenza del redattore rimane fondamentale
Processi e software non eliminano la necessità di competenze.
Una documentazione sostenibile richiede redattori capaci di governare almeno diversi ambiti.
Conoscenza normativa
Il redattore deve comprendere il quadro legislativo e normativo applicabile al prodotto per determinare quali informazioni devono essere fornite, a quali destinatari e in quali condizioni.
Scrivere informazioni inutili genera costi.
Non scrivere informazioni necessarie genera problemi molto più gravi.
Conoscenza tecnica
Per selezionare l’informazione necessaria bisogna comprendere il prodotto.
Meccanica, elettronica, automazione, pneumatica, idraulica e sicurezza non possono essere trattate come semplici parole da impaginare.
Il redattore deve capire ciò che sta comunicando.
Conoscenza linguistica
Scrivere in modo semplice, coerente e non ambiguo facilita comprensione, revisione, riuso e traduzione.
La lingua è quindi parte dell’efficienza del processo.
Conoscenza degli strumenti
Word, sistemi XML, CCMS, strumenti di traduzione, database terminologici e piattaforme di Content Delivery rispondono a esigenze differenti.
Non esiste uno strumento sostenibile in assoluto.
Esiste uno strumento adeguato al processo che dobbiamo gestire.
Logica e architettura dell’informazione
La capacità di organizzare l’informazione è probabilmente una delle competenze più importanti.
Occorre comprendere:
prodotto → destinatario → attività → informazione → struttura → pubblicazione
prima di scegliere il software con cui realizzarla.
Sostenibilità significa anche pubblicare una volta e distribuire dove serve
La stessa informazione può essere necessaria in contesti differenti.
- PDF.
- HTML.
- Tablet.
- Smartphone.
- QR code.
- Portale documentale.
- Knowledge base.
- Service.
- Formazione.
Creare manualmente contenuti separati per ciascun canale aumenta inevitabilmente il costo di gestione.
Una documentazione sostenibile tende invece a separare, quando il processo lo permette:
informazione
da
formato di pubblicazione.
Il contenuto può così essere riutilizzato e distribuito sui diversi canali senza dover essere necessariamente riscritto.
Vedi anche: PDF o HTML per la documentazione tecnica? Il vero problema è come strutturiamo l’informazione
La sostenibilità continua dopo la consegna della macchina
C’è un altro errore da evitare.
Considerare la consegna del manuale come la fine del processo documentale.
Per una macchina o un impianto la documentazione continua a vivere dopo la messa in servizio.
Possono cambiare:
- componenti;
- configurazioni;
- software;
- procedure;
- ricambi;
- schemi;
- informazioni di manutenzione.
La sostenibilità deve quindi riguardare anche la capacità di mantenere identificabile, raggiungibile e aggiornata la documentazione pertinente al prodotto durante il suo ciclo di vita.
La domanda diventa:
quale documentazione descrive oggi lo stato della macchina?
È in questa fase che sistemi di Content Delivery come CONTAINER possono intervenire nella distribuzione e nell’accesso alla documentazione tecnica.
Attraverso un ID-link o un QR code associato alla macchina, l’utilizzatore può accedere da smartphone, tablet o computer alla documentazione che la riguarda e raggiungere le informazioni necessarie quando servono.
Il principio rimane:
macchina → identificazione → documentazione pertinente → informazione necessaria
Vedi anche: CONTAINER: la piattaforma di Content Delivery per la documentazione tecnica di macchine e impianti
Digitale non significa automaticamente sostenibile
Trasformare un manuale cartaceo in PDF non rende automaticamente sostenibile la documentazione.
Possiamo avere un PDF di 800 pagine:
- difficile da consultare;
- pieno di duplicazioni;
- scarsamente aggiornabile;
- incoerente;
- difficile da tradurre;
- privo di una struttura informativa efficace.
Sarebbe digitale.
Ma non necessariamente sostenibile.
La digitalizzazione è uno strumento.
La sostenibilità dipende da come progettiamo, produciamo, manteniamo e distribuiamo l’informazione.
E l’Intelligenza Artificiale?
L’Intelligenza Artificiale può contribuire alla sostenibilità della documentazione, ma anche produrre l’effetto contrario.
Generare nuovo testo è diventato estremamente semplice.
Questo può portare a una proliferazione di contenuti, formulazioni e varianti che dovranno successivamente essere verificate e mantenute.
Per questo una domanda interessante non è soltanto:
“Cosa può scrivere l’AI per noi?”
ma:
“Può aiutarci a utilizzare meglio ciò che abbiamo già scritto?”
Una AI collegata a Translation Memory, Termbase, guida di stile e repository documentali potrebbe aiutare a:
- individuare contenuti simili;
- proporre frasi già validate;
- rilevare varianti terminologiche;
- segnalare termini obsoleti o proibiti;
- individuare possibili duplicazioni;
- supportare la revisione.
In questa prospettiva l’AI non serve necessariamente a produrre più contenuto.
Può servire a produrre meno contenuto nuovo e utilizzare meglio quello esistente.
Ed è una prospettiva molto più coerente con il concetto di documentazione sostenibile.
Come possiamo valutare se la nostra documentazione è sostenibile?
Possiamo partire da alcune domande.
Contenuto
- Sappiamo perché ogni informazione è presente?
- Abbiamo contenuti duplicati?
- Le informazioni sono orientate alle attività degli utilizzatori?
Redazione
- Esiste una guida di stile?
- I redattori utilizzano regole comuni?
- Prima di scrivere verifichiamo se esiste già un contenuto riutilizzabile?
Terminologia
- Utilizziamo una terminologia controllata?
- Sappiamo quali termini sono preferiti, obsoleti o proibiti?
- La terminologia è condivisa tra i reparti?
Traduzione
- Utilizziamo Translation Memory e Termbase?
- Il contenuto sorgente favorisce il riuso?
- Traduciamo contenuti che avremmo potuto evitare o riutilizzare?
Gestione
- Quando cambia un’informazione sappiamo dove è utilizzata?
- Quante volte dobbiamo correggere la stessa informazione?
- Gestiamo efficacemente prodotti e varianti?
Pubblicazione
- Possiamo produrre più output dallo stesso patrimonio informativo?
- Stiamo duplicando contenuti solo perché cambiano i formati?
Ciclo di vita
- La documentazione può essere aggiornata dopo la consegna?
- L’utilizzatore riesce a raggiungere la documentazione pertinente alla propria macchina?
- Sappiamo quale revisione descrive lo stato attuale del prodotto?
Più risposte negative troviamo, maggiore è probabilmente il debito documentale che stiamo accumulando.
Il debito documentale
Possiamo infatti prendere in prestito un concetto dal mondo dello sviluppo software.
Ogni scorciatoia che prendiamo oggi nella gestione dell’informazione può generare un costo futuro.
Copiamo una procedura invece di riutilizzarla.
Creiamo un altro termine invece di verificare quello esistente.
Manteniamo un paragrafo perché non abbiamo tempo di capire se serve.
Produciamo un altro file invece di intervenire sulla fonte.
Rimandiamo l’aggiornamento.
Nel breve periodo abbiamo risparmiato tempo.
Nel lungo periodo abbiamo creato debito documentale.
Prima o poi qualcuno dovrà pagarlo attraverso:
revisioni → verifiche → riallineamenti → ritraduzioni → correzioni → migrazioni.
La sostenibilità della documentazione tecnica consiste anche nel non trasferire sistematicamente al futuro il costo delle decisioni che prendiamo oggi.
Un esempio concreto: dal 20 gennaio 2027 cambia il Regolamento Macchine
Il passaggio dalla Direttiva 2006/42/CE al Regolamento (UE) 2023/1230, applicabile in via generale dal 20 gennaio 2027, offre un esempio molto concreto di cosa significhi sostenibilità della documentazione tecnica.
Pensiamo a un fabbricante che negli anni abbia sviluppato:
50 modelli di macchina → 50 manuali → diverse varianti → più lingue → documenti commercializzati in mercati differenti.
Quanti documenti dovranno essere verificati in vista dell’applicazione del nuovo Regolamento?
E quanto tempo sarà necessario per individuare tutti i punti nei quali la documentazione è legata al precedente quadro legislativo?
Il problema non consiste semplicemente nel sostituire in tutti i manuali:
Direttiva 2006/42/CE
con
Regolamento (UE) 2023/1230.
Occorre verificare quali informazioni siano realmente interessate dal nuovo quadro legislativo e quali documenti debbano essere aggiornati: modelli di manuale, dichiarazioni UE di conformità, riferimenti normativi, requisiti applicabili, modalità di fornitura delle istruzioni e altri contenuti collegati alla conformità della macchina.
Ed è in questo momento che emerge il debito documentale accumulato negli anni.
Se lo stesso riferimento è stato scritto manualmente in decine di documenti differenti, dovremo:
trovarlo → verificarlo → modificarlo → revisionarlo → ripubblicarlo → eventualmente ritradurlo.
Se invece l’informazione è stata progettata per essere controllata, riutilizzata e aggiornata attraverso fonti comuni, il cambiamento può essere gestito in modo molto più efficiente.
La differenza non diventa evidente quando produciamo il primo manuale.
Diventa evidente quando dobbiamo modificarne cinquanta.
Questo è uno degli aspetti più concreti della sostenibilità documentale:
non valutare quanto è semplice produrre oggi un documento, ma quanto sarà semplice modificare domani l’intero patrimonio documentale quando cambieranno prodotto, normativa o mercato.
Il Regolamento Macchine rappresenta quindi anche un’occasione per porsi una domanda più ampia:
quanto è sostenibile il nostro sistema documentale quando dobbiamo applicare una modifica trasversale a decine o centinaia di manuali?
La sostenibilità deve quindi essere valutata sul ciclo di vita della documentazione, non sulla singola commessa.
Documentazione sostenibile e ambiente
La sostenibilità documentale può avere anche conseguenze ambientali.
La distribuzione digitale può ridurre, quando appropriato, stampa, movimentazione e necessità di ristampare interi documenti a seguito di modifiche.
Processi più efficienti possono evitare lavorazioni e duplicazioni non necessarie.
Ma non è questo il significato principale che attribuiamo al termine.
Quando AP Publishing parla di Documentazione Tecnica Sostenibile, si riferisce innanzitutto alla capacità di progettare un sistema informativo che rimanga:
utile → gestibile → aggiornabile → riutilizzabile → economicamente sostenibile
durante il ciclo di vita del prodotto.
Gli eventuali benefici ambientali sono una conseguenza possibile di un processo meglio progettato, non uno slogan da attribuire automaticamente alla digitalizzazione.
Domande frequenti sulla sostenibilità della documentazione tecnica
Che cosa significa documentazione tecnica sostenibile?
Per AP Publishing significa progettare documentazione che possa essere creata, tradotta, pubblicata, utilizzata, aggiornata e mantenuta nel tempo con risorse proporzionate al valore dell’informazione fornita.
Sostenibilità significa soltanto ridurre il numero di pagine?
No. Ridurre contenuti necessari peggiorerebbe la documentazione. L’obiettivo è eliminare contenuti, duplicazioni e varianti che non producono valore mantenendo completezza, correttezza e usabilità.
Un CCMS rende automaticamente sostenibile la documentazione?
No. Un CCMS può facilitare modularità, riuso e gestione delle varianti, ma la sostenibilità dipende prima di tutto dalla progettazione dell’informazione e del processo.
Che rapporto c’è tra minimalismo e sostenibilità?
Il minimalismo riduce il contenuto non necessario. Meno contenuto superfluo significa meno informazioni da revisionare, tradurre, pubblicare e mantenere.
Translation Memory e Termbase possono contribuire?
Sì. Le Translation Memory favoriscono il riuso di formulazioni già prodotte e tradotte; i Termbase permettono di governare la terminologia. Entrambi possono ridurre la proliferazione di varianti non necessarie.
La documentazione digitale è più sostenibile?
Non necessariamente. Il formato digitale facilita alcune attività di distribuzione e aggiornamento, ma un contenuto digitale può essere ridondante, incoerente e difficile da mantenere esattamente come un documento cartaceo.
L’Intelligenza Artificiale rende la documentazione più sostenibile?
Dipende da come viene utilizzata. Se viene usata soltanto per generare altro contenuto può aumentare il volume da verificare e mantenere. Se viene utilizzata per recuperare, confrontare, controllare e riutilizzare conoscenza già validata può invece contribuire all’efficienza del processo.
La documentazione tecnica non finisce quando viene pubblicata
Il punto centrale è questo.
Una documentazione tecnica non dovrebbe essere valutata soltanto osservando il PDF che consegniamo oggi.
Dovremmo chiederci cosa succederà domani.
Quando cambierà il prodotto.
Quando dovremo creare una variante.
Quando arriverà un nuovo mercato.
Quando dovremo aggiungere una lingua.
Quando un manutentore avrà bisogno di quella procedura tra dieci anni.
Quando dovremo migrare i contenuti verso una nuova tecnologia.
Quando un’informazione dovrà essere aggiornata.
La vera domanda diventa quindi:
quanto sarà difficile mantenere corretta, coerente, traducibile, pubblicabile e utilizzabile questa informazione nel tempo?
Per AP Publishing è questo il significato di Documentazione Tecnica Sostenibile.
La documentazione tecnica non deve essere soltanto corretta quando viene consegnata. Deve essere sostenibile per tutto il suo ciclo di vita.
Quanto è sostenibile la vostra documentazione tecnica?
Manuali difficili da aggiornare, contenuti duplicati, terminologia incoerente, traduzioni ripetute e processi di pubblicazione troppo manuali generano costi che spesso emergono soltanto nel tempo.
AP Publishing può analizzare il vostro processo documentale per individuare duplicazioni, criticità di riuso, problemi terminologici, inefficienze nella traduzione, nella pubblicazione e nella gestione del ciclo di vita dell’informazione.
L’obiettivo non è semplicemente produrre documenti più velocemente.
È costruire un sistema documentale più utile oggi e più facile da mantenere domani.
RICHIEDI UN’ANALISI DEL PROCESSO DOCUMENTALE
Riferimenti
- IEC/IEEE 82079-1:2019, Preparation of information for use (instructions for use) of products – Part 1: Principles and general requirements.
- IEC 82079-1:2012, Preparation of instructions for use – Structuring, content and presentation – Part 1: General principles and detailed requirements, sostituita dalla IEC/IEEE 82079-1:2019.