PDF o HTML per la documentazione tecnica?
Sia il PDF che l’HTML sono formati di file utilizzati per rappresentare non solo testi e immagini, ma anche video e audio. Il PDF è associato al manuale cartaceo o al libro cartaceo. Il PDF avrà ancora lunga vita ma oggi il formato HTML è oggettivamente il più usato, da tutte le persone, in ambito generale. Gli utenti non si spaventano al download e apertura di un documento PDF, ma nel doverlo leggere. Nella documentazione tecnica, stiamo ancora producendo molti PDF (sinonimo di manuali tecnici da stampare su carta), ma è arrivata la tecnologia web e mobile, responsive, selettiva e il PDF così come lo abbiamo pensato fino ad oggi non è più usabile dagli utenti.
Qual è la differenza nell’usare un PDF o un HTML nella documentazione tecnica?
Navigando alla ricerca di definizioni e concetti, su wikipedia troviamo queste tre definizioni rispettivamente per PDF, Internet e Web:
“ […] il PDF è un formato di file basato su un linguaggio di descrizione di pagina sviluppato da Adobe Systems nel 1993 per rappresentare documenti di testo e immagini in modo indipendente dall’hardware e dal software utilizzati per generarli o per visualizzarli […]”.
“[…] Internet è la connessione che permette di mettere in comunicazione computer e dispositivi […]”.
“ […] Il World Wide Web è un servizio che opera attraverso internet ed è nato nel 1989 ma solo agli inizi del nuovo millennio si sviluppa come web 2.0. Adesso stiamo al 3.0 o web semantico[…]”.
Il PDF è nato e si è insediato in ogni angolo del Web. Il Web è sempre stato HTML. Hanno sempre convissuto sotto ai nostri occhi. I PDF sono aperti direttamente nei browser e questi hanno strumenti di visualizzazione avanzati, ma solo se il file sorgente del PDF viene creato con alcuni accorgimenti.
Il PDF è un formato di pubblicazione usato per lo più per libri o documenti più o meno lunghi, perché questo è il compito che gli abbiamo attribuito. Per natura, abbiamo scritto sempre libri e documenti che poi abbiamo trasformato in PDF per una visualizzazione e fruizione globale. Il PDF, per come lo abbiamo pensato fino ad ora, non sarà facile da usare per le generazioni future. In primis perché per loro un libro intero in cui cercare una singola informazione è troppo. Provate a mettere nella casella di ricerca di un PDF un’intera frase del tipo “come fare a sostituire la guarnizione del sullo superiore”, come siamo abituati a fare su Google! Cercare su Google non è come cercare in un documento PDF.
La pagina HTML è il Web per cui l’usabilità e la fruizione di contenuti è da sempre stato il cruccio dei webmaster da quando c’è il web semantico. Per il Web abbiamo scritto sempre singole pagine, nate e mantenute singole. Abbiamo creato modelli di contenuti, categorie e metadati (tag). Non esistono “libri ” per il web che si leggono con una continua azione sulla rotella del mouse. L’innovazione più grande del Web è stata la possibilità di pubblicare ipertesti i cui contenuti potevano risiedere su computer diversi connessi appunto via Internet.
Ora analizziamo i due formati di file, il PDF e l’HTML, nella documentazione tecnica.
In un file PDF possiamo trovare un intero manuale oppure organizzare un’intera documentazione tecnica. Con l’HTML, e quindi nel Web, visualizziamo sia la singola pagina o informazione ma possiamo organizzare l’intera conoscenza di una azienda.
Entriamo ora un po’ nel dettaglio tecnico.
Potremmo dire che un manuale o un libro è un insieme di informazioni e potremmo giungere alla conclusione che un titolo3 (h3) completo di paragrafi e immagini è esso stesso una singola informazione. Se estraiamo una singola informazione da un file PDF di un manuale (ad esempio tutto il blocco di informazioni contenute in un sottotitolo di un manuale) questo risulterà fuori dal contesto. Cioè il contesto è dato dal titolo1 che contiene i titoli2 e via via tutte le informazioni inerenti all’argomento enunciato nell’informazione presente nel titolo3.
Il manuale PDF, come un libro tradizionale, si fa e si legge in modo sequenziale
Oggi i file PDF di molti manuali hanno una organizzazione e rappresentazione dei contenuti che deve essere letta in modo sequenziale, dall’alto verso il basso, come un libro. Per la concezione che abbiamo oggi del file PDF l’informazione è dipendente dall’indice che ne specifica anche il contesto.
Se estraiamo da un manuale, una manutenzione dal titolo “Sostituzione della guarnizione del rullo superiore” troverò un insieme di immagini e testo con le istruzioni (avvertenze, obblighi e divieti a parte) che mi permettono di smontare la guarnizione. Ma le informazioni su cosa sia il rullo superiore, i nomi dei componenti, a cosa serve, dove si trovano le guarnizioni, la sicurezza del gruppo è stata riportata dal redattore in un’altra parte del manuale. L’indice stesso ci diceva, ad esempio, che la manutenzione si trova al capitolo 7 mentre la descrizione al capitolo 3. Non ci sono rimandi al paragrafo della descrizione del rullo superiore, neanche alle sue funzioni o alla sicurezza.
Se estraiamo la singola informazione, non è immediata la fruizione di contenuti a completamento dell’informazione stessa. Non ci sono (spesso) i riferimenti ad altre sezioni del manuale. Questo perché l’aver definito l’indice ed aver descritto le funzioni del gruppo da un’altra parte ci da l’idea della completezza delle informazioni, ma solo se abbiamo davanti il manuale completo. Cioè l’informazione è completa solo in presenza di tutte le altre informazioni. Così siamo stati abituati al libro!
Se prendiamo il solo paragrafo del libro fuori dal contesto ci accorgiamo che l’informazione è debole e manca di definizioni e geolocalizzazione.
Pagine HTML per comporre un manuale PDF
Prendendo più pagine HTML (ognuna completa con rimandi ad altre pagine) possiamo comporre un manuale e pubblicarlo in PDF per stamparlo su carta come richiesto dalla Direttiva Macchine? Si.
Possiamo da un manuale pensato come un libro, estrarre un’ informazione che soddisfi i criteri di univocità, completezza, ricercabilità dell’informazione? No, se continuiamo a scrivere “libri”
Serve un cambio di paradigma per scrivere il manuale in modo innovativo, fruibile in tutti i formati
Dobbiamo trovare un nuovo modo di scrivere ed organizzare le informazioni. Occorre un cambio di veduta per scrivere le informazioni di un prodotto, pensando non a dove saranno visualizzate o in che formato ma pensando alla loro completezza e peso specifico, metterle in relazione con le altre informazioni per poi comporre la documentazione che desideriamo.
Il PDF usato in senso tradiziole non è solo un formato destinato al cartaceo, è un’idea da abbandonare. Sia il formato PDF che l’HTML hanno la possibilità di inserire audio e video, entrambi si visualizzano nel browser.
Le aziende che oggi non pensano all’HTML come formato per la propria documentazione tecnica dovrebbero però pensare di strutturare comunque i contenuti. Creare contenuti pronti per il Web, riorganizzarli pensando più al prodotto, mettendolo al centro, scomponendolo in funzioni o gruppi funzionali, optional e poi rappresentare tutto di quel gruppo.
Imparare a scrivere informazioni complete e componibili
Dobbiamo imparare a scrivere informazioni complete, componibili, contestualizzate, in linea con le altre informazioni presenti nel medesimo livello. Le Informazioni dovranno essere complete di riferimenti e link ad informazioni collegate e appartenenti ad altri livelli di specificità dell’informazione. Solo così possiamo usare, raggruppare e visualizzare una informazione in qualsiasi modo. In PDF per stampare un manuale cartaceo (voluto ancora dalla Direttiva Macchine) o visualizzare l’HTML su un tablet a bordo macchina.
PDF non vuol dire lungo, completo o cartaceo e HTML non vuol dire wow! La bontà dell’informazione è quella che conta, la completezza, il suo peso specifico e l’indipendenza dalle informazioni del medesimo livello. Si ai collegamenti fra informazioni con peso specifico diverso, che fanno saltare di livello l’utente. Si ai collegamenti fra livelli del medesimo peso specifico per fare avanzare l’utente nella conoscenza del prodotto, passo passo.
Se pensiamo a come Google presenta la sua pagina (una barra di ricerca) si capisce come abbia predisposto un mezzo per soddisfare gli utenti alla ricerca di informazioni singole, specifiche che siano in grado di soddisfare le precise richieste di conoscenza dell’utente.
Iniziamo quindi a costruire informazioni modulari, componibili, specifiche delle funzioni del prodotto. Componiamo le informazioni per dare livelli di conoscenza del prodotto diverse, in base all’esperienza dell’utente. Il PDF e l’HTML sono formati di file e non daranno mai la loro autenticità, completezza, attualità. A questo deve ancora pensare il redattore con testo, immagini, audio, video e 3D interattivi utili anche per la realtà aumentata e virtuale.
