venerdì 27 giugno 2014

Dal "monolite" ai "moduli" ... con DITA: Task Topic

Nell'ultimo post di questo thread avevo iniziato a classificare le caratteristiche generali di un Topic, accompagnandole con dei semplici esempi. Vi avevo anche accennato a diverse metodologie (DITA, IM, S1000D, ...) finalizzate a definire la natura, la dimensione e la struttura di un Topic/modulo.

Oggi iniziamo a dare uno sguardo più approfondito a DITA, una delle metodologie più diffuse ed usate.

Qualcuno ricorderà che avevo già parlato e introdotto DITA in un articolo del 2013, prendendo spunto da un ottimo post di Petra Dal Santo.

In quel post sottolineavo la difficoltà di adottare DITA "a mani nude" ma riconoscendo, al tempo stesso, la notevole efficenza e struttura concettuale di questa metodologia, soprattutto quando si devono produrre grandi volumi di documentazione, magari in diverse lingue e formati.

Oggi userò DITA a titolo d'esempio, senza entrare in dettagli estremi che sono già ben affrontati in testi specialistici e che non avrebbe senso riportare pedissequamente, ma solo per enfatizzare alcuni aspetti "chiave" che possono spiegare meglio il passaggio critico dal "monolitico" al "modulare".

E quindi partiamo distinguendo tra i tre tipi principali di Topic:
  • Task
  • Concept
  • Reference

Task Topic

Un Task Topic racchiude delle indicazioni procedurali, di solito in formato step-by-step. In un Task Topic possono essere fornite indicazioni sul contesto in cui ha senso quell'indicazione ed eventuali prerequisiti necessari.

Un Task può innestarsi su uno o più concetti che saranno specificati in uno o più Concept Topic.

Ad esempio, se bisogna configurare un sistema di sensori ambientali attraverso un'interfaccia software, potrebbe essere necessario, per ogni sensore, richiamare (attraverso un link?) la descrizione dei parametri fisici misurati dal sensore.

Se ci sono  più modi alternativi per realizzare un certo compito, sarebbe opportuno documentare solo il più breve o il più utilizzato. Se è necessario documentare più modalità alternative, è opportuno costruire un Task Topic per ogni modalità.

Il titolo di un Task Topic deve essere preciso e deve indicare chiaramente la natura del Task.

Esempio (ERRATO):
Configurazione del sistema
... è un titolo vago che non spiega chiaramente nulla.

Esempio (CORRETTO):
Configurazione del Web Server su Ubuntu 12.04

Struttura di un Task Topic

- Introduzione, per indicare lo scopo della procedura
- Prerequisiti (se necessari)
- Procedura (di solito step by step)
- Chiusura

In particolare, se i prerequisiti sono presenti in un altro Topic, non replicate/copiate i contenuti ma definite un link verso di essi. Ovviamente si potrebbe anche usare il meccansimo della transclusion (ad esempio, per gli amanti di Flare, stiamo parlando degli Snippet... ci torneremo prossimamente), ma se non vogliamo legarci a soluzioni fuori standard, limitiamoci ad un link.

Una procedura composta da più di 8-9 passi risulterà poco "digeribile" ma questo dipende dalla natura del processo. Una volta mi è capitato do dover documentare un processo di ben 19 passi e non potevo "spezzarlo" o semplificarlo in alcun modo.

Di seguito, un breve esempio:


Tuttavia, valutate se un processo di N passi non possa essere suddiviso in sotto-processi di n1, n2, ... nk passi tali che: N = n1 + n2 + ... + nk

In questo caso, state descrivendo una super-procedura composta da k "procedure semplici" che vengono eseguite in sequenza. Ecco un esempio:


Qui vediamo un Super Task composto da 3 parti (Basic, General, Customization) ognuna delle quali è un Task specifico di un certo numero di passi.

Per approfondire questa tematica vi rimando a:

DITA Best Practices
IBM Style Guide

Leggi questo articolo...

domenica 22 giugno 2014

Un tessuto importante nasce dall'intreccio di fili diversi

Scusate l'assenza, ma ogni tanto bisogna prendersi del tempo per studiare e approfondire, oltre al tempo dedicato alle ordinarie attività professionali nella mia azienda, quanto mai intense nelle ultime 3 settimane.

Dove eravamo rimasti? Proviamo a riannodare alcuni fili, che sono naturalmente destinati ad intrecciarsi.


Ad Aix-en-Provence e prima ancora a Bologna sono partito da un'idea semplice: nell'era del Web 2.0/3.0 disponiamo di una massa di informazioni sostanzialmente infinita e che cresce ogni giorno, rispetto alla quale l'idea che sia l'utente a cercare le informazioni che gli necessitano è evidentemente improponibile e conduce a risultati deludenti: la maggiorparte dei dati che REALMENTE ci verrebbero utili per prendere decisioni semplicemente ci sfugge.

La soluzione risiede in un'altra idea semplice: rovesciamo il paradigma!

Non più l'utente che cerca l'informazione, ma l'informazione che cerca l'utente (Information Seeking User - ISeekingU), cioè sono le informazioni a "cercare" l''utente, in base al compito che l'utente deve compiere e al contesto in cui opera.

Le informazioni devono essere "task and context driven", cioè guidate dal compito che deve svolgere l'utente e dal contesto in cui si trova.

Il "mantra" da tenere a mente è:  fornire le informazioni giuste, alle persone giuste, nel tempo, nel luogo e nel modo giusti.

Se ci atteniamo alle raccomandazioni del minimalismo, questo significa  fornire solo le informazioni necessarie e sufficienti per permettere all'utente di svolgere il proprio compito in sicurezza ed efficacemente.

Un esempio significativo in tal senso è fornito dagli On Line Help presenti all'interno delle interfacce software dei dispositivi che usiamo ogni giorno.

Ma qui entra in gioco un primo elemento di rottura con lo schema classico, imperniato sul manuale stampabile tradizionale: un manuale è un oggetto sequenziale e gerarchico, dove il Cap. 3 arriva indefettibilmente dopo il Cap. 2 e inevitabilmente prima del Cap. 4.

Un manuale tradizionale, per sua natura, non può erogare informazioni guidate da compito e contesto; ci obbliga ad una lettura sequenziale.

Barbara Zen, in un recente post, si chiede, tra le altre cose, se le istruzioni per l'uso "si leggono o si consultano". Ai meno attenti potrebbe sembrare una domanda insolita, invece a me ha fatto venire in mente che "la consultazione" è la risposta "istintiva" dell'utente che ha un problema ben definito e che per risolverlo non ha nessuna intenzione di "leggere" tutta la documentazione disponibile, ma solo, appunto, "consultare" quella sezione specifica che risponde alla sua esigenza del momento.

Quindi se dobbiamo andare incontro ad una operatività "task/context driven", dobbiamo liberarci dal "gerarchico-sequenziale" e immaginare informazioni "modulari" che possono essere aggregate/collegate secondo percorsi diversi, come un ipertesto.

Per ottenere questo dobbiamo passare dalla gestione "monolitica" dei contenuti alla gestione di "moduli" riusabili focalizzati su un tema specifico (topic based).


Nel suo blog, Mark Baker indica questo approccio con il termine "bottom-up architecture", proprio in contrasto con la logica organizzativa di un libro tradizionale che segue, evidentemente, una logica "top-down".

Ovviamente, nulla ci vieta di ri-aggregare i nostri moduli secondo la stessa gerarchia presente nel manuale tradizionale, ma questa diviene una scelta "a valle" di un nuovo processo di gestione dei contenuti che può essere infinitamente più flessibile.

Come dico sempre, questo approccio non farà sparire i manuali  tradizionali, ma renderà la loro produzione "un effetto collaterale" di un processo molto più ricco di possibilità.

In altri termini, non "si parte" più dal manuale stampabile ma casomai "si arriva" ad esso, se e quando necessita.

Peraltro, vi invito a leggere un altro bel post di Barbara in cui sono indicati i vantaggi e gli svantaggi della digitalizzazione e della "scomparsa della carta" nella nostra vita di ogni giorno, dove si evidenzia che non sempre la scomparsa del supporto cartaceo può essere considerato un "sicuro" progresso.

E tuttavia, indipendentemente da come la pensiamo, è indubbio che la tendenza di medio-lungo periodo sarà basata sulla riduzione del supporto cartaceo, anche per via di vincoli legislativi che interessano diversi aspetti di qualsiasi attività produttiva, per ora soprattutto nell'ambito della Pubblica Amministrazione, ma presto anche per i privati cittadini/professionisti (conservazione sostitutiva, PEC, fatturazione elettronica, ...).

E questo lo sostengo sulla base di una seconda idea semplice: TUTTI i processi (produttivo-industriali, finanziari, commerciali, ...) DI OGNI GENERE, di qualsiasi livello o area tecnologica, sono già ora o saranno in futuro gestiti:
  • attraverso interfacce software
  • sempre più in modalità mobile
Vi sembra naturale avere in una mano un tablet, che vi permette di gestire un certo processo, e sfogliare con l'altra mano un manuale cartaceo per capire come completare QUEL PROCESSO?
O non vi sembrerebbe molto più naturale toccare con un dito la superfice del tablet e ottenere una forma di assistenza "embedded"?

Vi rammento che nel 2004 neanche immaginavamo le possibilità offerte da un tablet... ma nel 2024 (forse molto prima) consulteremo le istruzioni per montare i mobili della cucina con i Google Glass (o qualcosa di simile).

Come si gestisce tutto ciò?

Abbiamo bisogno di tecnologie/standard (CCMS, XML, XSLT, HTML5) e metodologie (DITA, IM, S1000D, ...), prima di tutto.

E abbiamo bisogno di diffondere queste conoscenze, ben aldilà della cerchia degli addetti ai lavori.

A presto.



Leggi questo articolo...