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
Nessun commento:
Posta un commento