Minimalismo nella documentazione tecnica: scrivere solo ciò che serve
Un manuale di 300 pagine è necessariamente più completo di un manuale di 150?
No.
La quantità di informazioni non determina automaticamente la qualità della documentazione tecnica. Un contenuto può essere completo e, allo stesso tempo, contenere ridondanze, spiegazioni inutili, ripetizioni, informazioni non pertinenti o dettagli che rendono più difficile individuare ciò che serve.
Il minimalismo nella documentazione tecnica consiste nel fornire le informazioni necessarie affinché i destinatari possano utilizzare il prodotto in modo sicuro, efficace ed efficiente, eliminando ciò che non contribuisce a questo obiettivo.
Non significa quindi scrivere poco.
Significa scrivere ciò che serve.
E questa distinzione ha conseguenze importanti non soltanto sulla leggibilità, ma anche sui costi di redazione, revisione, traduzione e mantenimento della documentazione durante l’intero ciclo di vita del prodotto.
Che cosa significa minimalismo nella documentazione tecnica?
Nel linguaggio comune il minimalismo viene spesso associato all’idea del less is more: eliminare ciò che è superfluo per concentrare l’attenzione su ciò che è essenziale.
Nella comunicazione tecnica il concetto è più preciso.
Il minimalismo deve trovare un equilibrio tra due esigenze apparentemente opposte:
completezza dell’informazione
e
assenza di informazioni non necessarie.
Una procedura non è minimalista perché è corta.
È minimalista quando contiene tutte e sole le informazioni necessarie al destinatario per svolgere correttamente l’attività prevista.
Questo significa che eliminare un’informazione necessaria non è minimalismo.
È semplicemente un’informazione incompleta.
Allo stesso modo, aggiungere informazioni perché “potrebbero essere utili” non rende necessariamente migliore un manuale.
Può renderlo più difficile da utilizzare.
Il minimalismo nella IEC 62079:2001
Il principio non nasce oggi.
Già la IEC 62079:2001 – Preparation of instructions – Structuring, content and presentation dedicava il paragrafo 6.1 ai principi di comunicazione.
Tra questi comparivano due indicazioni particolarmente significative:
- 6.1.4 – Simple and brief
- 6.1.7 – One sentence, one command
La norma introduceva quindi già più di vent’anni fa alcuni concetti che rimangono fondamentali nella redazione tecnica: semplicità, brevità, chiarezza dell’azione e riduzione dello sforzo necessario per comprendere un’istruzione.
Il principio one sentence, one command è particolarmente interessante.
Consideriamo questa frase:
Aprire il riparo, controllare che la macchina sia ferma, rimuovere il filtro e, dopo aver verificato che non sia danneggiato, sostituirlo se necessario.
Le informazioni possono essere tecnicamente corrette, ma sono concentrate in un’unica costruzione linguistica.
Una struttura orientata all’azione potrebbe invece essere:
- Arrestare la macchina.
- Aprire il riparo.
- Rimuovere il filtro.
- Verificare le condizioni del filtro.
- Sostituire il filtro se danneggiato.
Non abbiamo necessariamente eliminato parole.
Abbiamo eliminato complessità.
Ed è una distinzione fondamentale.
Dalla semplicità al principio di minimalismo
Con la IEC/IEEE 82079-1:2019 – Preparation of information for use (instructions for use) of products – Part 1: Principles and general requirements, il concetto viene formalizzato ulteriormente.
Il paragrafo 3.25 definisce il minimalismo come il principio secondo cui le informazioni per l’uso contengono le informazioni critiche e la quantità minima delle altre informazioni necessarie per risultare complete.
Il minimalismo diventa poi uno dei principi relativi alla qualità dell’informazione.
Il paragrafo 5.3 della IEC/IEEE 82079-1 considera infatti diversi aspetti:
- completezza;
- minimalismo;
- correttezza;
- concisione;
- coerenza;
- comprensibilità;
- accessibilità.
Il minimalismo non può quindi essere considerato isolatamente.
Un’informazione deve essere minimalista senza perdere completezza, correttezza e comprensibilità.
Questa è probabilmente la parte più importante del principio.
Minimalismo non significa togliere informazioni sulla sicurezza
C’è inoltre un’eccezione fondamentale.
Le informazioni relative alla sicurezza possono dover essere ripetute quando necessario.
Il principio di minimalismo non può essere utilizzato come giustificazione per eliminare un’avvertenza o un’informazione necessaria alla gestione di un rischio.
La domanda da porre non è quindi:
“Possiamo accorciare questo manuale?”
ma:
“Questa informazione è necessaria a questo destinatario, per questa attività, in questo momento?”
Il punto di partenza rimane sempre il destinatario e il compito che deve svolgere.
Il contrario del minimalismo è il rumore informativo
Quando revisioniamo documentazione tecnica preesistente troviamo frequentemente contenuti che si sono accumulati nel tempo.
Un’informazione viene aggiunta a una revisione.
Un’altra viene inserita dopo una richiesta del cliente.
Una frase viene duplicata in tre capitoli.
Una spiegazione viene copiata da un modello precedente.
Un paragrafo rimane nel manuale anche quando la macchina è stata modificata.
Nessuno elimina nulla perché prevale il principio:
“Nel dubbio, lasciamolo.”
Il risultato può essere un manuale formalmente ricco ma operativamente debole.
Il problema non è soltanto la quantità di pagine.
È il rumore informativo che si crea intorno all’informazione realmente necessaria.
Più informazioni presentiamo all’utilizzatore, più diventa importante permettergli di distinguere rapidamente ciò che gli serve da ciò che non gli serve.
Ogni informazione dovrebbe avere una ragione per essere presente
Durante la revisione di un contenuto tecnico possiamo applicare un criterio molto semplice.
Per ogni informazione chiediamoci:
Perché l’utilizzatore deve sapere questa cosa?
La risposta dovrebbe essere riconducibile a una necessità concreta.
Per esempio:
| Informazione | Perché serve? |
| Limite di carico | Evitare un utilizzo oltre i limiti previsti |
| Procedura di sostituzione filtro | Eseguire correttamente la manutenzione |
| Coppia di serraggio | Garantire il corretto rimontaggio |
| Rischio residuo | Permettere l’adozione del comportamento previsto |
| Qualifica richiesta | Identificare chi può eseguire l’attività |
| Descrizione generica del componente | Da verificare: serve realmente per il compito? |
Quest’ultima domanda è quella che spesso manca.
Nella documentazione tecnica siamo molto abituati a chiederci:
“Cosa dobbiamo aggiungere?”
Dovremmo imparare a chiederci anche:
“Cosa possiamo eliminare?”
Scrivere per attività, non per dimostrare quanto sappiamo della macchina
Un errore frequente consiste nel trasferire nel manuale una grande quantità di conoscenza tecnica disponibile sul prodotto.
Ma il manuale non deve necessariamente contenere tutto ciò che il progettista conosce della macchina.
Deve contenere ciò che serve ai suoi destinatari.
Un manutentore che deve sostituire un filtro potrebbe aver bisogno di conoscere:
- quando sostituirlo;
- quale ricambio utilizzare;
- quali condizioni di sicurezza devono essere stabilite;
- come accedere al componente;
- come rimuoverlo;
- come installare quello nuovo;
- quali verifiche eseguire prima della rimessa in servizio.
Potrebbe invece non aver bisogno di leggere tre pagine sulla storia progettuale del sistema di filtrazione.
Il minimalismo è quindi strettamente legato all’orientamento al destinatario e al task.
utente → attività → informazione necessaria
Una guida di stile aiuta a rendere il minimalismo ripetibile
Dire a un redattore “scrivi in modo semplice” serve relativamente poco.
Occorrono regole condivise.
Una guida di stile aziendale può trasformare principi generici in criteri applicabili durante la redazione.
Per esempio:
- una frase, un’azione principale;
- utilizzare verbi d’azione;
- evitare introduzioni prive di contenuto operativo;
- utilizzare sempre la stessa denominazione per lo stesso concetto;
- eliminare sinonimi non necessari;
- distinguere chiaramente descrizione, istruzione e informazione di sicurezza;
- utilizzare elenchi numerati per le sequenze operative;
- evitare di ripetere la stessa spiegazione in più punti quando non necessario;
- utilizzare immagini quando comunicano un’informazione meglio del testo;
- evitare immagini puramente decorative nella documentazione operativa.
La guida di stile permette quindi di trasformare il minimalismo da preferenza personale del redattore a regola del processo redazionale.
Riusare una buona frase è meglio che riscriverla ogni volta
La guida di stile produce però risultati soltanto se viene applicata nel tempo.
Supponiamo di aver definito, revisionato e approvato una frase:
Premere il pulsante START per avviare la macchina.
Se un secondo redattore scrive:
Agire sul tasto START per mettere in funzione la macchina.
e un terzo:
Premere il comando START per iniziare il funzionamento.
abbiamo creato tre varianti per esprimere sostanzialmente lo stesso concetto.
Ogni variante dovrà essere revisionata, tradotta e mantenuta.
Il minimalismo riguarda quindi anche la varietà linguistica non necessaria.
Se le frasi già approvate sono memorizzate in una Translation Memory, possono costituire un patrimonio riutilizzabile anche durante la redazione del testo sorgente.
È uno degli utilizzi che abbiamo previsto in Translations Base: permettere al redattore di cercare formulazioni già presenti nelle memorie di traduzione e verificare se esiste già una frase coerente con la guida di stile aziendale prima di crearne una nuova.
Il principio è semplice:
prima di riscrivere → cerchiamo se abbiamo già scritto.
La Translation Memory non sostituisce la guida di stile.
Può contribuire a renderne visibili e riutilizzabili i risultati.
Anche la terminologia deve essere minimalista
Lo stesso principio vale per i termini.
Se lo stesso componente viene chiamato alternativamente:
carter
riparo
protezione
schermo
l’utilizzatore deve prima capire se stiamo parlando dello stesso oggetto.
La varietà lessicale, apprezzabile in altri tipi di scrittura, può diventare rumore nella comunicazione tecnica.
Un Termbase permette di governare questa complessità stabilendo, per uno specifico contesto, quali termini sono validati, quali sono sinonimi, quali sono obsoleti e quali non devono essere utilizzati.
Anche in questo caso minimalismo non significa avere poche parole.
Significa evitare varianti prive di funzione.
Minimalismo e sostenibilità della documentazione tecnica
C’è poi un aspetto che viene considerato ancora troppo poco: la sostenibilità del contenuto.
Ogni frase che inseriamo in un manuale genera un costo.
Deve essere:
scritta → revisionata → approvata → impaginata → tradotta → pubblicata → aggiornata → verificata nel tempo.
Se il prodotto viene distribuito in dieci lingue, una frase inutile non rimane una sola frase inutile.
Diventa contenuto da gestire in undici lingue.
Se viene replicata in più manuali o varianti di prodotto, il costo si moltiplica ulteriormente.
Per questo il minimalismo non è soltanto un principio di leggibilità.
È anche un principio di sostenibilità economica e gestionale della documentazione tecnica.
Il contenuto superfluo ha un costo lungo tutto il ciclo di vita
Consideriamo un paragrafo di 100 parole che non aggiunge alcuna informazione utile.
Quelle 100 parole devono comunque essere:
- revisionate;
- eventualmente validate dal cliente;
- tradotte;
- controllate;
- gestite nelle revisioni;
- migrate quando cambia il sistema di authoring;
- mantenute coerenti con le modifiche del prodotto;
- pubblicate nei diversi formati.
Il costo della documentazione non dipende quindi soltanto dal costo iniziale della redazione.
Dipende dal costo totale di mantenimento del contenuto nel tempo.
Possiamo rappresentarlo così:
contenuto inutile × lingue × varianti × revisioni × anni di vita = costo documentale
Non è una formula economica, ma rende bene il problema.
Scrivere meno contenuto inutile significa anche tradurre meglio
La sostenibilità è particolarmente evidente nella traduzione.
Una frase superflua deve essere tradotta esattamente come una frase necessaria.
Una variante linguistica non necessaria può generare un nuovo segmento nella Translation Memory.
Un sinonimo introdotto casualmente può richiedere una verifica terminologica.
Una frase riscritta senza motivo può ridurre il riuso delle traduzioni precedenti.
Il minimalismo deve quindi iniziare prima della traduzione.
Una buona gestione del sorgente produce:
meno contenuto superfluo → maggiore coerenza → maggiore riuso → meno contenuto nuovo da tradurre → minore costo di mantenimento.
Questo non significa scrivere in funzione della Translation Memory.
La priorità rimane sempre fornire informazioni corrette, comprensibili e adeguate al destinatario.
Ma, a parità di efficacia, non esiste alcun vantaggio nel creare continuamente nuove formulazioni dello stesso concetto.
Un contenuto minimalista invecchia meglio
La sostenibilità riguarda anche il tempo.
Più informazioni inseriamo in un documento, maggiore è il numero di informazioni che dovremo verificare quando il prodotto cambia.
Questo è particolarmente evidente nella documentazione di macchine e impianti con un ciclo di vita lungo.
Una modifica a un componente può rendere obsolete:
- una descrizione;
- una procedura;
- un’immagine;
- un codice ricambio;
- un’avvertenza;
- un riferimento incrociato.
Se lo stesso contenuto è stato duplicato in più punti, dovremo individuarlo e aggiornarlo ovunque.
Il minimalismo si collega quindi direttamente anche al riuso e alla modularità dell’informazione.
Scrivere soltanto ciò che serve e riutilizzare ciò che è comune riduce il numero di informazioni che devono essere mantenute.
Minimalismo non significa soltanto meno testo
Il principio deve essere applicato all’intera informazione per l’uso.
Possiamo avere:
testo superfluo, quando spieghiamo ciò che il destinatario non ha bisogno di sapere;
immagini superflue, quando decorano ma non aiutano a identificare, localizzare o eseguire;
tabelle superflue, quando organizzano dati che non servono all’attività;
avvertenze superflue, quando segnaliamo genericamente pericoli senza fornire informazioni utili rispetto al rischio;
metadati superflui, quando classifichiamo il contenuto con informazioni che nessun processo utilizza;
duplicazioni superflue, quando manteniamo più copie dello stesso contenuto senza necessità.
Il minimalismo è quindi un principio di progettazione dell’informazione, non soltanto di scrittura.
Come applicare il minimalismo durante una revisione
Quando revisioniamo un manuale possiamo sottoporre ogni contenuto ad alcune domande.
A chi serve?
Se non sappiamo identificare il destinatario, probabilmente dobbiamo verificare la pertinenza dell’informazione.
Per quale attività serve?
Un’informazione dovrebbe supportare un compito, una decisione, la comprensione del prodotto o la gestione di un rischio.
È necessaria?
Se la eliminiamo, l’utilizzatore perde qualcosa di necessario per utilizzare il prodotto in modo sicuro, efficace o efficiente?
È già presente altrove?
Se sì, dobbiamo verificare se la ripetizione è realmente necessaria.
Possiamo dirlo in modo più semplice?
Non significa necessariamente usare meno parole. Significa ridurre lo sforzo necessario per comprenderle.
Esiste già una formulazione approvata?
La guida di stile, la Translation Memory e il Termbase possono aiutarci a evitare nuove varianti non necessarie.
Dovremo mantenerla nel tempo?
Ogni nuova informazione introduce anche un futuro obbligo di verifica e aggiornamento.
Completezza e minimalismo non sono contrari
Questo è forse il punto che deve rimanere dopo aver letto l’articolo.
Completezza e minimalismo non sono due estremi tra i quali scegliere.
Una buona informazione per l’uso deve essere entrambe le cose.
Deve contenere tutto ciò che serve.
E non deve essere appesantita da ciò che non serve.
La domanda corretta non è quindi:
“Quanto deve essere lungo un manuale?”
ma:
“Quali informazioni servono realmente ai destinatari per svolgere le attività previste in modo sicuro, efficace ed efficiente?”
Domande frequenti sul minimalismo nella documentazione tecnica
Minimalismo significa scrivere manuali più corti?
Non necessariamente. Significa eliminare le informazioni non necessarie. Un prodotto complesso può richiedere una documentazione estesa e rimanere perfettamente coerente con il principio di minimalismo.
Minimalismo e completezza sono in contraddizione?
No. La IEC/IEEE 82079-1 considera entrambi principi della qualità dell’informazione. Il minimalismo richiede di fornire le informazioni critiche e la quantità minima delle altre informazioni necessarie per garantire la completezza.
Posso eliminare informazioni sulla sicurezza per evitare ripetizioni?
Non automaticamente. Le informazioni relative alla sicurezza possono dover essere ripetute quando necessario. Il minimalismo non deve compromettere l’uso sicuro del prodotto.
Perché una guida di stile favorisce il minimalismo?
Perché stabilisce regole comuni per struttura delle frasi, terminologia, procedure, avvertenze e altri elementi della comunicazione tecnica, riducendo variazioni e contenuti non necessari.
Che rapporto esiste tra Translation Memory e minimalismo?
Una Translation Memory permette di recuperare formulazioni già utilizzate e tradotte. Se le frasi sono state redatte secondo la guida di stile aziendale, il loro riuso può contribuire a mantenere coerenza e a evitare la proliferazione di nuove varianti linguistiche.
Perché il minimalismo rende la documentazione più sostenibile?
Perché ogni contenuto deve essere prodotto, revisionato, tradotto, pubblicato e mantenuto. Eliminare contenuti e varianti non necessari riduce il volume di informazioni da gestire durante il ciclo di vita della documentazione.
La regola da ricordare del minimalismo
Potremmo sintetizzare il principio in una regola:
Non chiederti quanto puoi togliere. Chiediti che cosa deve rimanere perché l’utilizzatore possa fare ciò che deve fare.
Tutto ciò che rimane deve avere una funzione.
Deve aiutare a comprendere.
A decidere.
Ad agire.
A evitare un errore.
A gestire un rischio.
A trovare un’informazione.
Il resto genera rumore.
E il rumore nella documentazione tecnica non è gratuito: deve essere scritto, revisionato, tradotto, pubblicato e mantenuto per tutta la vita del prodotto.
Per questo il minimalismo non è soltanto un principio di buona scrittura.
È un principio di qualità, usabilità e sostenibilità della documentazione tecnica.
Quanto contenuto superfluo c’è nei vostri manuali?
Un manuale può essere tecnicamente corretto e allo stesso tempo contenere informazioni ridondanti, formulazioni incoerenti e contenuti che nel tempo devono essere revisionati, tradotti e mantenuti senza produrre un reale valore per l’utilizzatore.
AP Publishing può supportarvi nella revisione della documentazione tecnica esistente, verificando struttura dei contenuti, coerenza terminologica, applicazione della guida di stile, possibilità di riuso e adeguatezza delle informazioni rispetto ai destinatari e alle attività da svolgere.
L’obiettivo non è semplicemente ridurre il numero di pagine, ma rendere la documentazione più utile, coerente e sostenibile nel tempo.
RICHIEDI UNA REVISIONE DELLA DOCUMENTAZIONE TECNICA
Riferimenti
- IEC 62079:2001, Preparation of instructions – Structuring, content and presentation, in particolare 6.1.4 Simple and brief e 6.1.7 One sentence, one command.
- IEC/IEEE 82079-1:2019, Preparation of information for use (instructions for use) of products – Part 1: Principles and general requirements, in particolare 3.25 Minimalism e 5.3.3 Minimalism.