Perché e come pubblicare online la documentazione tecnica e di prodotto

postato da Petra Dal Santo - KEA s.r.l. [23/02/2015 11:46]
foto

La documentazione tecnica ai tempi del web. Oltre manuali di istruzioni ed help online: il modello della User Assistance. Report sul libro di Mark Baker, Every Page is Page One. Topic based writing for Technical Communication and the Web, XML Press, Laguna Hills, California, 2013

Obiettivi del volume

Gli obiettivi dichiarati del libro di Baker sono:

  • Accrescere l’utilità dei contenuti creati dai comunicatori tecnici
  • Aiutare chi sviluppa software a realizzare sistemi in grado di supportare il processo di redazione e pubblicazione dei contenuti.

Fruizione delle informazioni “nel contesto del web”

Dal momento che le persone sono connesse in modo sempre più persistente, secondo Baker il modello dominante di ricerca e fruizione delle informazioni è quello online, che le persone tendono ad applicare anche quando non sono online.

Le caratteristiche principali del modello di ricerca e fruizione delle informazioni “nel contesto del web” sono:

  • Motori di ricerca e filtri permettono all’utente di trovare in modo autonomo e dinamicamente le informazioni di volta in volta utili allo scopo
    • Motori e filtri sono strumenti facili (più facili del sommario o degli indici di un manuale), che permettono all’utente di dialogare (quasi) in linguaggio naturale, di ottenere risultati provenienti da diverse fonti (non da un’unica come nel caso di un manuale) e di filtrare a valle i contenuti più interessanti
    • Grazie agli esigui costi di pubblicazione e alla socialità, rispetto alla carta sul web trovano spazio anche contenuti specialistici (a coda lunga), nonché informazioni basate su esperienze reali e destinate alla soluzione di problemi pratici. Dal momento che, in prevalenza, la ricerca sul web ha come finalità l’azione e che quindi l’utente cerca informazioni azionabili nel suo contesto operativo, la possibilità di trovare contenuti di nicchia e provenienti dal “mondo reale” è molto apprezzata
    • Sul web l’utente adotta strategie di ricerca simili a quelle dei predatori, atte a trovare nel minor tempo e con il minor dispendio possibile informazioni sufficientemente soddisfacenti (in inglese “satisficing”). Per seguire la pista, l’utente consuma piccole porzioni di informazione, che gli permettono di capire al volo se il contenuto è adeguato o se passare oltre. Per l’utente “ogni pagina è pagina 1”, perché egli non fruisce delle informazioni in modo sequenziale, ma “salta” da una pagina all’altra, da un sito all’altro, alla veloce ricerca di contenuti utili
    • Obiettivo della comunicazione tecnica è veicolare l’informazione giusta alla persona giusta, nel momento giusto, nella lingua giusta e tramite il dispositivo scelto dalla persona. Ecco perché è importante pubblicare sul web la documentazione tecnica (non riservata), favorendone indicizzazione e posizionamento, e rendendola filtrabile da parte degli utenti
  • Mentre sulla carta la classificazione dei contenuti è monodimensionale, sul web ogni contenuto può essere associato, in modo multidimensionale, a più chiavi di ricerca
  • L’aggregazione delle informazioni non è predefinita dall’autore (come nel caso di un manuale), ma definita localmente dall’utente in base alle proprie esigenze momentanee
    • Le informazioni non sono organizzate in modo gerarchico e sequenziale, ma “Every Page is Page One” (EPPO). Nella lista dei risultati del motore o del filtro “ogni pagina è pagina 1”, cioè una pagina singola, citata fuori dal contesto del sito di cui fa parte e i contenuti devono essere fruibili indipendentemente
  • Le informazioni, cioè le singole pagine, non sono dipendenti l’una dall’altra, ma stanno fra loro in un rapporto Peer-to-Peer (P2P), paritetico
  • Le informazioni sono collegate fra loro in base ad affinità semantiche, di soggetto (per accedere a informazioni più generiche o più specifiche).

Architettura dell’informazione top-down tipica di manuali su carta ed help online classici

A proposito dell’architettura dell’informazione di manuali cartacei ed help online classici, Baker sottolinea che:

  • Manuali di istruzioni su carta
    • Il sommario rappresenta la struttura gerarchica del documento. Si tratta di una struttura visibile in modo ottimale solo dall’esterno, cioè consultando il sommario, non dall’interno delle singole pagine
  • Help online classici
    • Nel caso dell’help online, la classica architettura tripartita della videata (sopra il motore di ricerca, a sinistra l’albero di navigazione e a destra i contenuti) mantiene sempre visibile la struttura del documento.

Sia nel caso dei manuali di istruzioni su carta che degli help online classici, la struttura del documento è predefinita dall’autore. L’utente ha poche possibilità di ricercare, filtrare e aggregare le informazioni in base alle proprie esigenze puntuali.

I singoli capitoli non sono concepiti secondo la logica “ogni pagina è pagina 1”, ma inseriti in una classificazione gerarchica, pensata per la fruizione sequenziale. Ecco perché la pubblicazione sul web della versione digitale di manuali cartacei o di help online non risponde in modo ottimale alle esigenze informative degli utenti provenienti da ricerche sui motori.

Il mondo fisico impone il vincolo di organizzare i contenuti in base a gerarchie monodimensionali, fondate sulla selezione da parte dell’autore dei termini di aggregazione da lui giudicati prioritari. Nel caso di elementi non inseribili univocamente in un solo insieme, questo rappresenta un limite: se il fruitore non (ri)conosce la logica e/o la terminologia sottesa alla classificazione adottata dall’autore, egli rischia di non trovare il contenuto di suo interesse.

Nel mondo digitale le gerarchie possono essere multidimensionali (classificazione a faccette). Un elemento può appartenere contemporaneamente a più insiemi. Benché anche la classificazione multidimensionale sia opera dell’autore, e implichi quindi una condivisione di logica e terminologia fra autore e fruitore, motori di ricerca interni ai singoli siti e filtri attivi su diversi attributi / valori danno all’utente maggiore libertà di ricercare, filtrare ed aggregare le informazioni su basi semantiche.

Baker non suggerisce di accantonare tout court la classificazione gerarchica dei contenti, ma di:

  • Adottare sistemi di classificazione condivisi con i destinatari delle comunicazione tecnica, in modo tale che possano facilmente essere riconosciuti
  • Realizzare la documentazione tecnica da pubblicare sul web seguendo il principio per cui “ogni pagina è pagina 1”, corredando le pagine di metadati multidimensionali e di link paritetici ad altre pagine semanticamente affini
  • Riconoscere la specificità dei due approcci:
    • La classificazione gerarchica, monodimensionale, supporta la fruizione sequenziale, su carta, dei contenuti, ma risulta anche utile all’utente che accede alla home page del nostro sito e desidera approfondire via via la conoscenza di un argomento
    • “Ogni pagina è pagina 1” + metadati + link paritetici vengono incontro all’utente web che proviene da un motore di ricerca “globale” (come Google) o che utilizza il motore / i filtri interni al nostro sito.

Architettura dell’informazione bottom-up tipica del web (modello della “user assistance”)

Usciamo dal mondo della carta e dai mondi rappresentati dai singoli siti, ed entriamo nell’universo del web. I motori di ricerca “globali” aggregano i risultati in modo semantico, dinamico e paritetico, in base all’espressione chiave cercata dall’utente.

I risultati della ricerca rappresentano un universo in cui non è l’autore a costruire staticamente, a priori, la relazione gerarchica monodimensionale fra i contenuti, ma è un software (il motore di ricerca) a costruire dinamicamente, a posteriori rispetto alla domanda dell’utente, la relazione paritetica fra pagine semanticamente affini.

In questo contesto l’autore ha il compito di:

  • Rendere i contenuti reperibili attraverso Google e gli altri motori di ricerca “globali”
  • Organizzare i contenuti in topic, in “monadi” informative - di cui vedremo le caratteristiche più avanti
  • Costruire la rete di link paritetici fra topic secondo la logica dell’affinità semantica
  • Si tratta di un punto particolarmente importante: in assenza di link fra topic, l’utente ricorre nuovamente al motore di ricerca globale per cercare contenuti più generali o più specifici. Così facendo esce dal nostro “mondo” (cioè dal nostro sito). I link fra topic danno l’opportunità di soddisfare le esigenze informative dell’utente, facendolo permanere all’interno del nostro contesto, anche se egli non percepisce il nostro sito come totalità
  • Ogni topic va visto come un hub verso altri topic affini per soggetto, più generici e/o più specifici.

Topic: “monadi” informative a misura di web (“ogni pagina è pagina 1”)

Baker sottolinea che il termine topic ha due possibili accezioni:

  • Segmento di contenuto. Per utilizzare la metafora del Lego, il segmento di contenuto è un mattoncino riusabile con altri mattoncini per ottenere N costruzioni. Il mattoncino è un oggetto distinto, ma non autonomo, perché è funzionale a integrarsi senza attrito con altri mattoncini per realizzare costruzioni. Alcuni mattoncini possono essere dipendenti dal contesto, cioè presupporre la presenza, prima e dopo, di determinati altri mattoncini. Baker non utilizza il termine topic in questa accezione
  • Aggregato di segmenti di contenuto. Se il segmento di contenuto rappresenta il singolo mattoncino, l’aggregato è una delle costruzioni realizzabili. Baker utilizza il termine topic in questa accezione, cioè come aggregato di informazioni utile al fruitore (per esempio per aiutarlo a portare a termine un compito). Per Baker un topic è, per esempio, una ricetta di cucina, non i singoli ingredienti o le singole fasi della procedura.

Nell’accezione di Baker, il topic è un insieme di contenuti dotato delle seguenti caratteristiche principali:

  • Autosufficienza, intesa come indipendenza dal contesto. Ogni topic è di senso compiuto, la sua comprensione non dipende dalla consultazione di altri topic. L’utente consulta altri topic solo per generalizzare o specializzare le proprie conoscenze
    • Definizione del proprio contesto. Il topic, come la maggior parte degli articoli di Wikipedia, si apre con una brevissima introduzione che colloca il topic “nel mondo reale”, fornendone le coordinate e chiarendone lo scopo. Sulla carta la contestualizzazione avviene attribuendo a un capitolo una determinata posizione all’interno del sommario; nel contesto del web (“ogni pagina è pagina 1”), contestualizzare significa introdurre correttamente il topic, disambiguare termini, dotare il topic di metadati atti a favorirne ricerca e filtraggio, completarlo con link a topic paritetici semanticamente affini
  • Limitazione e specificità. Ogni topic va dedicato a un solo soggetto, limitato e specifico
  • Orientamento all’azione. Il topic è task oriented, contiene informazioni azionabili, cioè utilizzabili dall’utente per portare a termine un compito. Baker sottolinea che ciò non significa che nei topic non vadano inserite informazioni sul prodotto e sulle sue caratteristiche, ma che devono essere funzionali allo svolgimento dell’azione
    • L’orientamento all’azione implica che il topic deve non solo illustrare le fasi di una procedura, ma fornire anche supporto decisionale all’utente. Il topic non deve solo dire all’utente di premere un bottone, ma dargli gli strumenti per comprendere quando e perché premerlo, e quali sono le conseguenze. Per Baker l’esposizione del “come” è conseguente a quella del “perché”
  • Adesione a una tipologia standard. Nella maggior parte dei settori vi sono tipi di contenuto standardizzati, a livello legale, normativo o consuetudinario. Per esempio, un utente che consulta una ricetta si aspetta di trovare il titolo, una breve introduzione, un’immagine esemplificativa, la lista degli ingredienti, la procedura ed eventualmente gli abbinamenti (di vini o altro). L’adesione alla tipologia di riferimento ne agevola il riconoscimento e la fruizione da parte dell’utente
    • I tipi di topic di Baker sono più specifici delle tipologie definite da DITA (concept, task e reference), poiché tengono anche conto del compito che descrivono e della struttura delle informazioni attesa dall’utente. Nei topic di Baker il compito non è riducibile a informazioni procedurali, poiché comprende anche elementi utili a supportare il percorso decisionale. Le reference non coincidono con la loro rappresentazione in tabella (tipica del medium cartaceo), ma sono concettualmente basi dati interrogabili in modo multidimensionale da parte dell’utente (per esempio: sul manuale di istruzioni cartaceo il piano delle manutenzioni è rappresentato tradizionalmente in tabella. Pubblicando online la documentazione tecnica, tuttavia, la tabella andrebbe sostituita da un motore di ricerca e da filtri interni al sito, che permettono all’utente di trovare le informazioni in base a vari criteri: numero di ore, parte della macchina, ricambio, qualifica dell’operatore, utensili richiesti, ecc.). Infine, Baker critica il fatto che in DITA ciò che non è task o reference sia automaticamente etichettato come concetto: vi possono essere topic dedicati a concetti, ma altri sono semplicemente testi: introduttivi, esemplificativi (per esempio di un codice sorgente), ecc.
  • Presupposizione della qualifica dell’utente. Ogni topic si rivolge a un destinatario qualificato a svolgere il compito descritto, adottandone la terminologia tipica. Se l’utente non è sufficientemente qualificato, i link a contenuti più generali gli permettono di auto-formarsi, acquisendo le conoscenze necessarie. Per esempio: la ricetta dice “cuoci la pasta”; se l’utente non sa come cuocere la pasta, nel topic non troverà la spiegazione (perché la ricetta si rivolge a un cuoco e presuppone che il cuoco, in quanto tale, sappia cuocere la pasta), ma un link a questo argomento semanticamente affine. In alternativa è possibile dedicare topic diversi a diversi destinatari tipici, adeguando contenuti, terminologia e metadati
  • Link a topic paritetici, semanticamente affini, in grado di fornire contenuti più generali o più specifici.

Baker sottolinea che i contenuti del topic non si limitano a testi, ma possono includere qualsiasi oggetto multimediale.

Scrivere topic a misura di web (“ogni pagina è pagina 1”)

Non è un manuale di istruzioni su carta, non è un classico help online... Baker definisce “User Assistance” il tipo di pubblicazione a misura di web, basato su topic, in cui “ogni pagina è pagina 1”.

Nella redazione topic, il comunicatore tecnico dovrebbe seguire il filo rosso delle caratteristiche elencate già sopra:

  • Autosufficienza, intesa come indipendenza dal contesto
  • Definire il proprio contesto
  • Focalizzazione su un solo soggetto, limitato e specifico
  • Orientamento all’azione e supporto decisionale
  • Adesione a una tipologia standard, condivisa con il destinatario tipico della comunicazione
  • Presupposizione della qualifica dell’utente
  • Link a topic paritetici, semanticamente affini.

E il quadro d’insieme?

Nei manuali di istruzione su carta il quadro d’insieme (“big picture”) è dato essenzialmente dal sommario, poiché spesso non è presente un capitolo introduttivo.

Fruendo delle informazioni “nel contesto del web”, l’utente non parte dal quadro d’insieme, ma da esigenze specifiche: lo svolgimento di un compito, la soluzione di un problema. Tuttavia, l’utente può avere la necessità di ricostruire via via dal basso un quadro d’insieme. Ecco perché ogni topic può contenere link a topic semanticamente affini in grado di generalizzare, oltre che di specializzare la conoscenza.

Baker definisce tre macro-tipologie di topic, correlabili da link paritetici:

  • Big picture topic”: illustra i singoli principi base di un dominio di conoscenza
  • Pathfinder topic”: illustra il flusso di lavoro (in cui si collocano i singoli compiti) o descrive a livello macro un determinato compito (in cui collocano le singole fasi)
  • Nel caso in cui sia necessario definire la sequenza (cioè il “prima” e il “dopo”) interna a un insieme di task topic, è opportuno dedicare un pathfinder topic all’esposizione dell’ordinamento. Contrariamente al sommario classico, i singoli pathfinder topic possono essere multidimensionali, esponendo l’ordinamento in base a specifici punti di vista (per esempio: diversi tipi di contesti operativi, flussi di lavoro, ruoli, compiti, ecc.)
  • Task topic”: è dedicato a un compito limitato e specifico oppure a una singola fase in sé conchiusa.

Editing modulare e strutturato

Baker individua due modalità di editing strutturato:

  • Editing strutturato retorico. Definisce, ma non formalizza, le tipologie di topic (per esempio: articolo di giornale, saggio, ricetta, scheda prodotto, ecc.)
  • Editing strutturato computabile. Definisce e formalizza le tipologie di topic, in modo tale da rendere strutture e contenuti elaborabili da parte di applicazioni software. DITA, S1000D, schemi industriali verticali sono esempi di strutture computabili.

I vantaggi della modularizzazione e delle strutture computabili sono:

  • Garanzia che - almeno dal punto di vista formale - il contenuto sia tipizzato, completo, coerente e navigabile, contribuendo a migliorarne la qualità
  • Guida alla redazione e alla gestione dei metadati
  • Elaborabilità da parte di applicazioni software (motori di ricerca, filtri, ecc.). I topic - nati per la fruizione nel contesto del web, secondo il modello della “user assistence” - possono comunque essere assemblati, anche automaticamente, nelle strutture gerarchiche di manuali di istruzione su carta e di help online classici. L’inverso non è invece possibile
  • Orientamento alla SEO (Search Engine Optimization), ovvero all’indicizzazione e al posizionamento da parte dei motori di ricerca “globali”
  • Interoperabilità (scambio di dati fra applicazioni)
  • Orientamento verso il futuro (in particolare se si adottano standard aperti è più semplice migrare i contenuti in caso di obsolescenza di formati e applicazioni)
  • Single sourcing (gestione univoca del contenuto) e riuso in vari media, tipi di pubblicazioni e pubblicazioni
  • Gestione collaborativa dei contenuti e integrazione di contributi specialistici
  • Supporto alla produzione di documentazione tecnica nel contesto dell’accorciamento del ciclo di vita dei prodotti e della mass customization (personalizzazione di massa)
  • Supporto all’aggiornamento, alla pubblicazione di nuova documentazione tecnica e alla rimozione di contenuti obsoleti “a ciclo continuo”. Dal momento che “ogni pagina è pagina 1”, ogni topic (aggiornato, nuovo o eliminato) è “plug&play”, non implica una revisione dell’intera struttura gerarchica (come sarebbe nel caso del manuale su carta o dell’help online classico).

Metadati dei topic

Baker sottolinea che i metadati vanno definiti prima dei contenuti e associati a essi in modo tendenzialmente automatico (cioè dalle applicazioni software, non dalle persone).

I metadati vanno pensati in modo gerarchico, in modo tale da adeguarli ai diversi livelli di segmentazione e di aggregazione dei contenuti.

Esempi di metadati citati da Baker sono: lo schema di un determinato tipo di topic, il sommario di un documento cartaceo, gli indici, coppie di attributi / valori, ecc.

Link paritetici fra topic semanticamente affini

Come già per i metadati, anche per la creazione dei link Baker punta sull’automazione.

Il metodo che descrive è quello del Soft Linking, in cui applicazioni software generano in modo automatico e dinamico i link paritetici fra topic, in base ai metadati associati a essi e alle affinità semantiche (cioè alle relazioni fra i metadati) gestite dal redattore. Gli insiemi di link sono di solito presentati come lista all’interno del singolo topic.

I vantaggi principali del Soft Linking sono:

  • Risparmio di tempo
  • Incremento dinamico dei link nel tempo (a mano a mano che si aggiungono nuovi topic semanticamente affini)
  • Coerenza, intesa come indipendenza dalla soggettività dei redattori
  • Assenza di link interrotti (in caso di rimozione di contenuti obsoleti), grazie alla generazione dinamica degli stessi.

Riuso dei contenuti

Baker individua due accezioni del termine riuso:

  • Riuso dei contenuti in tipi di pubblicazione e pubblicazioni diverse. Per tipi di pubblicazione intendiamo, per esempio, manuali di istruzione, help online, guide al troubleshooting, cataloghi ricambi, ecc. Per pubblicazioni intendiamo manuali dedicati a singoli modelli di un prodotto
  • Riuso dei contenuti in vari media (multicanalità): carta, web...

Sulla carta il riuso dei contenuti è statico e implica una duplicazione (o meglio: una moltiplicazione) dei contenuti: per inserire un contenuto in più manuali devo riprenderlo per link o per contenuto (by reference o by copy) e poi pubblicare gli N manuali contenenti il contenuto riusato.

Nel contesto del web il riuso del contenuto è dinamico, guidato dalle esigenze informative dell’utente, e non implica alcuna duplicazione. Grazie ai metadati, motori di ricerca “globali”, motori di ricerca e filtri “locali” (presenti cioè sul nostro sito) permettono all’utente di trovare lo stesso contenuto, se adeguato, in contesti di ricerca diversi.