Nel mio continuo lavoro di ricerca nel campo della Com Tecnica, sono capitato per caso sul sito di Canonical e da lì mi sono imbattuto in Diátaxis, un framework per la realizzazione della documentazione di prodotto ideato da Daniele Procida. Questo il suo sito.
Diátaxis è un termine che deriva dal greco antico: dia
(“attraverso”) + taxis (“disposizione, ordine”). L’idea di base è che la
documentazione deve essere organizzata in modo che gli utenti trovino ciò di
cui hanno bisogno in funzione del loro scopo.
Diátaxis divide la
documentazione in quattro tipi:
- Tutorial:
guide per apprendere facendo, passo dopo passo.
- How-to:
contenuti focalizzati sulla risoluzione di use case specifici.
- Reference:
descrizioni tecniche, specifiche, tabelle, parametri, API, etc.
- Explanation:
contenuti concettuali, background, contesto, per aiutare a comprendere più
a fondo.
Diátaxis si pone l’obiettivo di aiutare gli utenti a
trovare più facilmente ciò che cercano, perché l’organizzazione dei contenuti è
basata sui loro obiettivi.
Quindi possiamo dire che il framework cerca di assumere “il
punto di vista dell’utente”, e questa è una tendenza conforme ad altre
discipline che si sono imposte negli ultimi 25 anni (vedi Design Thinking).
I principi di fondo che possiamo individuare sono sostanzialmente 2:
- Fornire un modello coerente per organizzare la documentazione di prodotto.
- Netta separazione di contenuti diversi, finalizzati per utenti diversi che le utilizzano in momenti diversi: le spiegazioni concettuali (Explanation) servono per dare una base ed un contesto, ma gli How To sono le vere procedure operative per risolvere problemi specifici.
Analizziamo sinteticamente le 4 tipologie di documentazione.
TUTORIAL
Sono finalizzati ad insegnare attraverso la pratica. L’obiettivo
è “imparare facendo”, non “capire leggendo”.
Guidano l’utente passo dopo passo nel completamento di un
compito, per acquisire nuove abilità in modo esperienziale. Un buon tutorial
porta l’utente a fare un percorso di apprendimento, in cui ogni passaggio
costruisce comprensione e fiducia.
Non confondete il Tutorial con l’How To:
- Secondo Diàtaxis, un Tutorial guida l’utente per imparare (la definizione di una
configurazione, il disegno di un modello, etc)
- Un How To aiuta a risolvere uno specifico use-case (come faccio a fare QUESTA
cosa?)
Un Tutorial efficace dovrebbe:
- Dichiarare l’obiettivo: cosa avrò imparato al termine?
- Prerequisiti: cosa serve sapere prima di iniziare.
- Istruzioni passo passo: ogni passo, istruzioni brevi e una sola azione (un solo verbo) per ogni passo.
- Un risultato tangibile: qualcosa di concreto da mostrare.
- Un riepilogo e i prossimi passi: come continuare a imparare o approfondire.
EXPLANATION (concetti e spiegazioni)
Le spiegazioni servono a fornire contesto, comprensione e concetti, al fine di rispondere alla domanda: “Perché funziona così? In base a quali concetti o principi?”
A differenza dei Tutorial, le spiegazioni non sono istruzioni. Il loro scopo è aiutare il lettore a capire, non a fare.
Un Explanation efficace include:
- La definzione del concetto: cosa si sta spiegando e perché è rilevante.
- Principi chiave: le definizioni.
- Contesto e background: come si collega ad altre parti del sistema o della Teoria.
- Dettagli, esempi e controesempi: per chiarire il funzionamento e i limiti.
- Collegamenti ad altri concetti o decisioni progettuali: come si è arrivati a una certa scelta?
- Riepilogo finale e suggerimenti per approfondire: testi, documenti o sezioni correlate.
In Diàtaxis, le spiegazioni non vanno messe nel Tutorial o nell’How To.
Se un Tutorial inizia a spiegare teoria, o un How To si dilunga in
riflessioni, significa che quelle parti dovrebbero essere spostate nella
sezione Explanation.
REFERENCE (riferimenti tecnici)
I documenti di riferimento sono la parte più tecnica e dettagliata della documentazione. Servono a descrivere in modo preciso e completo come funziona il sistema o il prodotto. Non insegnano, non spiegano concetti e non risolvono problemi concreti: descrivono.
Una Reference ben fatta è esaustiva e facilmente consultabile. È utile per chi sa già cosa vuole fare, ma ha bisogno di conoscere i dettagli esatti per riuscirci.
Elementi tipici di una buona Reference includono:
- Descrizioni complete di funzioni, comandi, classi o API.
- Tabelle di parametri, argomenti, tipi di dati e valori di ritorno.
- Esempi per illustrare come utilizzare correttamente una funzione o un’opzione.
- Diagrammi o schemi strutturali, per capire la relazione tra elementi.
- Collegamenti incrociati verso sezioni correlate (es. verso guide o spiegazioni).
La Reference deve essere organizzata in modo coerente ed ogni
elemento documentato (una funzione, un comando, un endpoint API, ecc.) dovrebbe
seguire lo stesso schema informativo.
Essa richiede un approccio descrittivo e non
dovrebbe essere presente all’interno di un Tutorial o di un Explanation.
HOW TO
Servono a completare un compito specifico e rispondono alla domanda: come faccio a fare QUESTA cosa?
Un How To definisce una procedura specifica che consente di ottenere un risultato preciso.
Un How To deve:
- Definire l’obiettivo: cosa si otterrà al termine della procedura.
- Elencare i prerequisiti.
- Fornire istruzioni step-by-step.
- Includere esempi concreti.
- Concludere con un riepilogo e collegamenti utili (ad esempio ad altre guide o sezioni di riferimento).
----
Potrebbe essere interessante valutare l'eventuale correlazione tra Diàtaxis e altri standard/framework/metodi per la documentazione tecnica, quali DITA, S1000D e Information Mapping.
DITA vs Diàtaxis
DITA è uno standard aperto basato su XML per strutturare, creare e pubblicare contenuti modulari che possono essere facilmente riutilizzati su piattaforme diverse, consentendo una gestione efficiente della documentazione tecnica, attraverso la creazione di contenuti basati sulla specializzazione dei contenuti.
E' forse lo standard tecnico più utilizzato nel mondo, e non solo per la documentazione dei prodotti software come erroneamente molti pensano.
DITA organizza le informazioni in piccoli “topic” autonomi tipizzati per Concept-Task-Reference-Troubleshooting.
Tali topic sono assemblati utilizzando un organizzazione gerarchica (DITA Maps), promuovendo la coerenza, la scalabilità e la riduzione dei costi nella gestione di grandi volumi di documentazione.
Qulcuno intuisce un qualche punto di contatto?
"Concettualmente" si. Analizziamo la seguente tabella.
Ma è importante capire che queste "similitudini" sono solo apparenti.
DITA lavora a livello di "topic" che può essere un frammento di informazione "piccolo a piacere", da poche righe a pochi pararagrafi. Inoltre, ogni elemento della struttura del topic è associato ad un tag XML preciso. E ci sono topic che possono contenere solo un certo insieme di DITA tag e non altri.
Invece in Diàtaxis un How To può essere un documento anche molto esteso, purchè coerente con i principi sopra indicati. Gli elementi informativi di un How To in Diàtaxis non sono legati a nessuno tipo di tag XML e quindi non presentano una struttura pre-definita.
DITA parte con l'idea di organizzare i contenuti dal punto di vista della loro "struttura tecnica interna".
Diàtaxis parte del punto di vista dell'utente che deve consultare i documenti.
Quindi la tabella è un classico caso di "correlazione ingannevole": sia DITA che Diàtaxis indicano alcune "tipologie" di contenuto, ma la correlazione è debolissima, perchè la classificazione tipologica si applica ad oggetti diversi.
S1000D vs Diàtaxis
S1000D è anch'esso uno standard tecnico XML largamente utilizzato in tutto il mondo, in special modo nell'industria navale (civile e militare), in quella ferroviaria e in quella avionica/aeronautica (civile e militare). La sua "tipizzazione" è molto più dettgliata e raffinata di quella di DITA.
Un oggetto S1000D è definito da una specifica estremamamente precisa in ogni dettaglio informativo.
Direi che possiamo certamente concludere che S1000D e Diàtaxis sono imparagonabili.
Information Mapping vs Diàtaxis
Information Mapping (IM) è un metodo strutturato e modulare per scrivere contenuti in modo che siano facilmente comprensibili e riutilizzabili, concentrandosi sulla granularità e sull'uso di elementi visivi come le "mappe di contenuto" (content maps).
IM si focalizza sulla struttura fisica del contenuto (blocchi di testo, dati, immagini) che sono auto-contenuti, coerenti e riutilizzabili (tabelle, liste).
IM prescrive la rigorosa modularità dei contenuti, utilizzando principi di design per creare blocchi di informazione che possono essere riassemblati.
IM non è uno standard XML aperto.
Diàtaxis, come abbiamo visto, è un framework molto più incentrato sul COSA e sul PERCHE', che parte dal punto di vista dell'utente: non prescrive regole rigide sulla struttura fisica dei contenuti, e nemmeno sui blocchi informativi da presentare all'utente.
Tuttavia, sia IM che Diàtaxis hanno in comune l'aspirazione di promuovere l'organizzazione logica dei contenuti e la scomposizione di informazioni complesse, al fine di migliorare la comprensione e ridurre il carico cognitivo per chi legge.
IN CONCLUSIONE
Diàtaxis è un framework interessante, con pochissimi punti di contatto con gli standard tecnici XML più usati nel mondo (DITA ed S1000D), mentre presenta qualche affinità con una metodologia come IM.
Come sempre, non esiste la soluzione perfetta per ogni contesto.
Pe grandi volumi di dati, che devono essere aggiornati di frequente, customizzati in N modi diversi e tradotti in dozzine di lingue, la potenza tecnico-organizzativa di DITA è difficilmente contrastabile.
S1000D lo potete pensare come DITA elevato all'ennesima potenza, non a caso si usa in contesti e per prodotti spesso "mission-critical" dove la standardizzazione e la precisione dei contenuti sono imprescindibili.
Ma per altri contesti, adottare DITA ed S1000D potrebbe essere paragonabile ad andare a caccia di fagiani con un missile terra-aria.
Diàtaxis ha il grande pregio di essere focalizzato sulle esigenze degli utenti, con un'organizzazione semplice ed elegante. E non è un pregio trascurabile.
