PDF o HTML per la documentazione tecnica? Il vero problema è come strutturiamo l’informazione?

PDF o HTML per la documentazione tecnica? Il vero problema è come strutturiamo l’informazione?

PDF o HTML: qual è il formato migliore per un manuale tecnico?

La risposta è: dipende da come e dove deve essere utilizzata l’informazione.

Il PDF continua a essere un formato estremamente efficace per distribuire, archiviare, scaricare e stampare documenti completi. L’HTML, invece, permette di costruire esperienze di consultazione più dinamiche, responsive e orientate alla ricerca della singola informazione.

Ma concentrarsi esclusivamente sul formato rischia di farci perdere il problema principale.

Prima di scegliere PDF o HTML dobbiamo decidere come strutturare l’informazione tecnica.

Se il contenuto è progettato correttamente, infatti, la stessa informazione può essere riutilizzata e pubblicata attraverso canali differenti.

Qual è la differenza tra PDF e HTML nella documentazione tecnica?

Il PDF rappresenta molto bene il concetto di documento.

Un manuale può essere distribuito come un unico file, conservando struttura, impaginazione, immagini, tabelle e sequenza dei contenuti.

L’HTML permette invece di lavorare più facilmente secondo una logica basata su informazioni collegate tra loro, che possono essere ricercate, visualizzate e raggiunte indipendentemente dal documento completo.

In termini molto semplici:

PDF	HTML
È particolarmente efficace per distribuire un documento completo	È particolarmente efficace per distribuire informazioni collegate
Mantiene una struttura editoriale definita	Permette navigazione dinamica
È facilmente scaricabile e archiviabile	È naturalmente utilizzabile attraverso browser
Può essere stampato mantenendo l’impaginazione	Può adattarsi a dispositivi differenti
La consultazione parte normalmente dal documento	La consultazione può partire dalla singola informazione
È adatto alla conservazione di una versione documentale	È adatto a creare sistemi informativi navigabili

Non significa che uno sia migliore dell’altro.

Significa che rispondono bene a esigenze differenti.

Un PDF non è necessariamente “carta digitale”

È importante evitare un’equivalenza troppo semplice:

PDF = carta
HTML = digitale.

Un PDF può contenere collegamenti, segnalibri, metadati ed elementi interattivi e può essere consultato direttamente attraverso un browser.

Allo stesso modo, una pagina HTML mal progettata può offrire un’esperienza peggiore di un buon PDF.

Il formato, da solo, non determina quindi la qualità della documentazione.

La vera domanda è:

quanto facilmente l’utilizzatore riesce a raggiungere l’informazione di cui ha bisogno?

Dal documento all’informazione

Un manuale tradizionale viene normalmente progettato secondo una struttura gerarchica (top down):

manuale

→ capitolo

→ sezione

→ paragrafo

→ informazione.

Il contesto di un’informazione dipende spesso dalla posizione che occupa all’interno di questa struttura.

Pensiamo a una procedura dal titolo:

Sostituzione della guarnizione del rullo superiore

All’interno del manuale il lettore può comprendere il contesto grazie alle sezioni precedenti.

La descrizione del gruppo potrebbe essere al capitolo 3.

Le informazioni sulla sicurezza al capitolo 4.

La manutenzione al capitolo 7.

La distinta dei ricambi in un altro documento.

Finché l’utilizzatore consulta il manuale completo, questa struttura può funzionare.

Ma cosa succede se vogliamo fornire direttamente quella singola procedura?

Una singola informazione deve poter essere compresa nel proprio contesto

Se estraiamo una procedura dal documento che la contiene, dobbiamo verificare che continui a essere comprensibile (bottom up).

L’utilizzatore deve poter capire almeno:

• a quale macchina o prodotto si riferisce
• quale componente riguarda
• chi può eseguire l’attività
• in quali condizioni deve essere eseguita
• quali sono i prerequisiti
• quali rischi devono essere considerati
• quali utensili o materiali sono necessari
• quali operazioni devono essere svolte
• quali informazioni correlate possono essere necessarie.

Questo non significa duplicare continuamente le stesse informazioni.

Significa progettare le relazioni tra le informazioni.

La procedura può contenere collegamenti verso la descrizione del componente, le informazioni di sicurezza, il ricambio o un’altra procedura correlata.

Informazioni complete, modulari e componibili

È qui che cambia il modo di progettare la documentazione tecnica.

Invece di pensare esclusivamente:

“Devo scrivere un manuale.”

possiamo iniziare a pensare:

“Quali informazioni servono all’utilizzatore per conoscere, utilizzare e manutenere questo prodotto?”

Possiamo quindi organizzare contenuti relativi a:

• descrizione
• funzionamento
• sicurezza
• installazione
• utilizzo
• regolazione
• manutenzione
• diagnostica
• ricambi
• dismissione.

Ogni informazione deve avere un proprio scopo e un proprio contesto e deve poter essere collegata alle altre informazioni necessarie.

Il manuale diventa così una delle possibili composizioni di queste informazioni, non necessariamente l’unico modo per renderle disponibili.

Perché questo cambia la documentazione digitale

Immaginiamo un manutentore davanti a una macchina che visualizza:

Errore E04.

In quel momento probabilmente non vuole consultare l’intero manuale dall’inizio.

Vuole sapere:

• Cosa significa E04?
• Quali possono essere le cause?
• Quali controlli devo effettuare?
• Posso intervenire autonomamente?
• Quale procedura devo seguire?
• Quando devo contattare il service?

Un sistema di documentazione digitale può portare l’utilizzatore direttamente a queste informazioni e collegarle tra loro.

Il passaggio concettuale è quindi:

cercare un documento

→ cercare un’informazione.

Ed è questa differenza, più del formato PDF o HTML, a determinare il valore della documentazione digitale.

Informazioni strutturate significa anche informazioni riutilizzabili

Quando un’informazione viene progettata come unità autonoma e strutturata, può essere riutilizzata in contesti differenti.

Una procedura di manutenzione, per esempio, potrebbe essere utilizzata:

• nel manuale PDF
• nella documentazione HTML
• su un tablet
• attraverso un QR code a bordo macchina
• in un portale di assistenza
• in una knowledge base
• durante un’attività di formazione
• come informazione collegata a un ticket del service.

Il contenuto viene quindi separato, per quanto possibile, dal formato finale di pubblicazione.

Questo principio è alla base degli approcci single sourcing e della documentazione strutturata.

PDF e HTML possono convivere

Non dobbiamo quindi necessariamente scegliere tra PDF e HTML.

Un sistema documentale può utilizzare entrambi.

La stessa base informativa può alimentare differenti output in funzione delle necessità.

Per esempio:

PDF

per download, archiviazione, stampa e disponibilità del manuale completo.

HTML

per consultazione online, navigazione, ricerca e accesso diretto alle singole informazioni.

Il punto fondamentale è progettare i contenuti prima dell’output.

Non dovremmo scrivere pensando esclusivamente alla pagina A4 o alla pagina web.

Dovremmo progettare informazioni che possano essere pubblicate nel formato più adatto al contesto di utilizzo.

Cosa cambia con il Regolamento Macchine (UE) 2023/1230?

Quando questo articolo fu pubblicato nel 2019, il quadro normativo di riferimento era la Direttiva 2006/42/CE.

Con il Regolamento (UE) 2023/1230 il tema della documentazione digitale assume un’importanza ancora maggiore.

Il Regolamento, applicabile dal 20 gennaio 2027, consente di fornire le istruzioni per l’uso in formato digitale nel rispetto delle condizioni previste.

Tra gli aspetti da considerare rientrano l’indicazione delle modalità di accesso alle istruzioni digitali, la possibilità di stamparle e scaricarle e la loro disponibilità online per il periodo previsto dal Regolamento.

Il formato digitale non coincide necessariamente con HTML.

Può essere utilizzato anche un PDF.

La questione centrale rimane quindi la stessa:

non quale formato è “digitale”, ma come rendere l’informazione accessibile e utilizzabile nel contesto in cui serve.

Per approfondire: Regolamento Macchine 2023/1230: il futuro della documentazione tecnica tra digitale e carta

Dalla ricerca nel manuale al self-service tecnico

La struttura dell’informazione ha conseguenze anche sul servizio post-vendita.

Se un operatore riesce a trovare autonomamente:

• il significato di un allarme
• una procedura
• la posizione di un componente
• uno schema
• un ricambio
• una regolazione

può risolvere direttamente una parte delle richieste informative senza dover necessariamente contattare l’Help Desk.

Non significa sostituire il service.

Significa permettere al service di concentrarsi sui problemi che richiedono realmente competenza tecnica.

Abbiamo approfondito questo aspetto nell’articolo Ridurre i tempi dell’Help Desk con la documentazione tecnica: dal ticket al self-service.

Informazioni strutturate e Intelligenza Artificiale

Oggi esiste un’ulteriore ragione per progettare informazioni autonome, contestualizzate e semanticamente chiare: l’utilizzo dell’Intelligenza Artificiale per l’accesso alla conoscenza tecnica.

Un sistema AI che deve rispondere alla domanda:

“Come sostituisco il filtro principale della macchina X?”

deve poter individuare:

• il prodotto corretto
• la configurazione corretta
• la procedura pertinente
• i prerequisiti
• le condizioni di sicurezza
• le informazioni correlate.

Se queste informazioni esistono soltanto implicitamente all’interno di documenti lunghi e dipendono fortemente dal contesto delle pagine precedenti, il recupero della risposta diventa più complesso.

Se invece sono strutturate, contestualizzate e collegate semanticamente, possono essere recuperate e riutilizzate più facilmente.

È interessante notare che questo principio non nasce con l’Intelligenza Artificiale.

È un principio della buona comunicazione tecnica.

L’AI ne rende semplicemente ancora più evidente il valore.

Dal PDF al Content Delivery

A questo punto la domanda iniziale cambia.

Non è più:

PDF o HTML?

Diventa:

come dobbiamo organizzare l’informazione tecnica affinché possa essere distribuita nel modo più efficace per ogni utilizzatore e contesto?

Questo porta dal concetto di semplice pubblicazione documentale a quello di Content Delivery.

L’utilizzatore non deve necessariamente conoscere il nome del documento che contiene la risposta.

Deve poter raggiungere l’informazione attraverso elementi come:

• prodotto
• numero di serie
• configurazione
• componente
• attività
• errore
• ruolo
• contesto operativo.

CONTAINER: dalla documentazione al punto di utilizzo

È in questa logica che si inserisce CONTAINER, la piattaforma sviluppata da AP Publishing per la distribuzione della documentazione tecnica digitale.

Attraverso un ID-link o un QR code associato alla macchina, l’utilizzatore può accedere alla documentazione tecnica che la riguarda da smartphone, tablet o computer.

L’obiettivo non è semplicemente mettere online dei PDF.

È creare un collegamento tra:

prodotto → documentazione → utilizzatore → informazione.

Manuali, schemi, procedure, video, informazioni di manutenzione e contenuti relativi ai ricambi possono così essere messi a disposizione nel contesto in cui vengono utilizzati.

Domande frequenti

È meglio utilizzare PDF o HTML per un manuale tecnico?

Non esiste un formato universalmente migliore. Il PDF è particolarmente efficace per distribuire, archiviare, scaricare e stampare un documento completo. L’HTML consente invece una navigazione più dinamica e un accesso più diretto alle singole informazioni. La scelta deve dipendere dal contesto di utilizzo.

Il PDF è considerato un formato digitale?

Sì. Un manuale in PDF è un documento digitale. Il formato digitale previsto dal Regolamento (UE) 2023/1230 non deve essere necessariamente HTML.

Un manuale HTML può sostituire un PDF?

Dipende dai requisiti applicabili e dal sistema di pubblicazione. HTML e PDF possono anche essere due output della stessa base informativa strutturata e svolgere funzioni differenti.

Cosa significa documentazione tecnica strutturata?

Significa organizzare i contenuti secondo unità informative definite e relazioni esplicite, anziché considerarli esclusivamente come pagine consecutive di un documento. Questo facilita riuso, aggiornamento, ricerca e pubblicazione multicanale.

Perché le informazioni modulari sono importanti per l’Intelligenza Artificiale?

Perché informazioni autonome, contestualizzate e semanticamente definite possono essere individuate e recuperate più facilmente quando un sistema deve rispondere a una domanda specifica. La modularità, tuttavia, deve mantenere le relazioni necessarie per interpretare correttamente l’informazione.

Conclusione: non scegliamo il formato prima di progettare l’informazione

PDF e HTML sono i formati con cui sono rappresentate le informazioni.

La qualità della documentazione dipende innanzitutto dalla qualità delle informazioni che contiene e dal modo in cui queste vengono strutturate.

Per questo la domanda:

“Dobbiamo fare il manuale in PDF o HTML?”

dovrebbe arrivare dopo.

Prima dovremmo chiederci:

Quali informazioni servono all’utilizzatore, in quale contesto gli servono e come possiamo strutturarle affinché siano complete, trovabili, aggiornabili e riutilizzabili?

Una volta progettata correttamente l’informazione, possiamo decidere come distribuirla:

PDF, HTML, mobile, QR code, video, sistemi di Content Delivery o applicazioni basate sull’Intelligenza Artificiale.

Il formato cambia.

L’informazione è il patrimonio da progettare e gestire.

AP Publishing

AP Publishing progetta documentazione tecnica per macchine, impianti e prodotti partendo dalla struttura dell’informazione e dal contesto nel quale dovrà essere utilizzata.

Dalla redazione tecnica alla documentazione strutturata, dalla comunicazione visuale alla distribuzione digitale, l’obiettivo è trasformare documenti e dati tecnici in informazioni realmente utilizzabili durante il ciclo di vita del prodotto.

Con CONTAINER, queste informazioni possono essere distribuite digitalmente e rese disponibili anche direttamente nel punto di utilizzo attraverso ID-link e QR code.