Report sull’utile testo introduttivo di Sandra Uris, Managing Your First S1000D Project. A Guide For Technical Publication Managers, San Diego, CA, 2014 (seconda edizione)

1. Kea s.r.l. | Via Strà, 102 | 37042 Caldiero (VR)
Tel.: +39 045 6152381
Web: www.keanet.it | E-mail: info@keanet.it
S1000D: alla scoperta della specifica che
regola la comunicazione tecnica nel
settore aerospaziale e della difesa
Report sull’utile testo introduttivo di Sandra Uris, Managing Your First
S1000D Project. A Guide For Technical Publication Managers, San Diego,
CA, 2014 (seconda edizione)
Nata nel settore aerospaziale e della difesa, anche la specifica S1000D si basa sui principi del single sourcing
(all’interno di un Common Source Database [CSDB]), della modularizzazione, della marcatura e del (ri)uso
dei contenuti (chiamati Data Modules, simili ai topic di DITA), nonché dell’aggregazione dinamica di output
multicanale.
“Take the time for plan!”: in base all’esperienza di Sandra Uris, la pianificazione è fondamentale per la
buona riuscita di un progetto S1000D. Per progetti di piccole dimensioni (fino a 2.000 Data Modules circa) è
necessario considerare circa 3 settimane di pianificazione preliminare, che salgono a 9-10 settimane nel
caso di progetti più corposi. Nella pianificazione è opportuno coinvolgere non solo risorse provenienti dallo
studio di comunicazione tecnica (comunicatori tecnici, illustratori, informatici, ecc.), ma anche il
committente.
Le tappe fondamentali del processo di pianificazione di un progetto S1000D sono:
• Definizione della versione di S1000D da utilizzare
• Definizione delle Business Rules
• Definizione della Data Modules Requirements List (DMRL)
• Definizione della Functionality Matrix, in particolare se l’output è di tipo Interactive Electonic
Technical Manual / Publication (IETM / IETP)
• Scelta dei tool di authoring, di delivery e di display da utilizzare.
Definizione della versione di S1000D da utilizzare
La versione corrente della specifica S1000D è la 4.1. Sandra Uris sottolinea, che fra le versioni 2.0 e 3.0 (pur
diverse fra loro) e la versione 4.0 vi è uno stacco sensibile, poiché cambia la struttura dei tag. Dal momento
che la migrazione da una versione all’altra è onerosa, l’autrice consiglia di definire con cura la versione della
specifica da utilizzare, optando per la più recente nel caso in cui non vi fossero vincoli da parte del
committente.
Definizione delle Business Rules
Le Business Rules, da formalizzare in un Data Module apposito denominato Business Rules Exchange
(BREX), riguardano in particolare:
• Capitoli, sottocapitoli e sezioni applicabili al progetto
1
S1000D
Petra Dal Santo (dalsanto@keanet.it)

2. Kea s.r.l. | Via Strà, 102 | 37042 Caldiero (VR)
Tel.: +39 045 6152381
Web: www.keanet.it | E-mail: info@keanet.it
• Tipi di Data Modules (cioè Info Set) applicabili al progetto, e relativi tag, attributi e valori utilizzabili.
Document Type Definition [DTD] / schemi sono utili non solo come guida in fase di redazione, ma
possono essere usati anche per automatizzare la validazione della correttezza formale dei Data
Modules
• Regole relative a:
o Nominazione di DataModule e immagini. Il nome dei file XML / SGML (chiamato Data
Module Code [DMC]) e dei file JPG / CGM (chiamato Illustration Control Number [ICN]) è
parlante e fondamentale per identificare in modo univoco i file contenenti testi e immagini.
In base alla versione della specifica S1000D adottata, per esempio il DMC si compone di
min. 17 / max. 37 caratteri, che identificano: prodotto e variante di prodotto; capitolo,
sottocapitolo e sezione; codice di disassemblaggio e sue varianti; tipo di Data Module (es. il
codice 520 identifica un Data Module dedicato a una procedura di Rimozione; il 720 un
Data Module dedicato a una procedura di Installazione); luogo in cui l’azione si svolge
tipicamente
o Versionamento
o Redazione di testi e creazione di immagini
• Output da produrre, forme di presentazione e funzionalità, in particolare nel caso di help online
come gli Interactive Electonic Technical Manual / Publication (IETM / IETP)
• Scelta dei tool di authoring e di validazione, di delivery e display da utilizzare.
Il BREX può essere usato per automatizzare per esempio la validazione delle writing rules specifiche del
progetto.
Definizione della Data Modules Requirements List (DMRL)
Si tratta della lista dei Data Modules di cui il committente richiede lo sviluppo nell’ambito di uno specifico
progetto S1000D. Serve come base per la preventivazione, per la redazione e per la verifica dei materiali
consegnati.
Definizione della Functionality Matrix
Se il committente richiede la consegna della documentazione sotto forma di Interactive Electonic Technical
Manual / Publication (IETM / IETP), è necessario definire una lista delle funzioni che l’help online deve
supportare (es. navigazione, ricerca, ecc.). Le IETM / IETP possono essere consultate dall’utente attraverso
viewer oppure erogate da un software a bordo macchina in base al contesto d’uso in cui si trova la persona.
La differenza fra IETM e IETP sta nel fatto che l’Interactive Electonic Technical Manual è un singolo manuale
(es. di istruzioni d’uso o di manutenzione), mentre l’ Interactive Electonic Technical Publication è una
raccolta di pubblicazioni (es. manuale di installazione, uso e manutenzione e catalogo ricambi).
Scelta dei tool di authoring, di delivery e di display da utilizzare
In S1000D è centrale il Common Source Database (CSDB), un repository di file XML / SGML per i testi e di
file JPG / CGM (Common Graphics Metafile) per le immagini.
Nel caso di progetti di piccole dimensioni (fino a 1.000 Data Modules circa), secondo Sandra Uris il CSDB
può essere costituito anche da un semplice file system. Per progetto più corposi, il ricorso a un tool
dedicato è invece imprescindibile.
2
S1000D
Petra Dal Santo (dalsanto@keanet.it)

3. Kea s.r.l. | Via Strà, 102 | 37042 Caldiero (VR)
Tel.: +39 045 6152381
Web: www.keanet.it | E-mail: info@keanet.it
Il ricorso al file system (semplice ed economico), presenta comunque alcuni svantaggi anche nel caso di
progetti di piccole dimensioni: il rischio di spostamenti e cancellazioni involontari; la difficoltà a gestire il
versionamento; l’impossibilità di automatizzare le operazioni di validazione; necessità di ricorrere a tool
dedicati per aggregare i Data Modules negli output in base a condizioni date.
Fra i vantaggi che normalmente presentano i tool CSDB, spiccano: gestione del check-in / -out per
agevolare il lavoro collaborativo; gestione delle autorizzazioni, tracking delle modifiche e versionamento;
validazione dei Data Modules in base a DTD / schemi e BREX; tool di publishing integrati.
***
Autore: Petra Dal Santo (dalsanto@keanet.it)
http://blog.keanet.it
www.keanet.it
3
S1000D
Petra Dal Santo (dalsanto@keanet.it)