Lo Zen e la Qualità della documentazione tecnica
La Qualità della documentazione tecnica: Chiarezza e Sintesi
La Qualità non è un pranzo di gala
La Qualità della documentazone tecnica: la Leggibilità
La Qualità nella documentazione tecnica: lo scalpello di Michelangelo... o la sua mente?
Oggi voglio illustrare un altro aspetto che contribuisce in maniera decisiva ad incrementare la Qualità di un documento, cioè il processo di controllo e validazione che deve sempre essere implementato per ridurre al minimo sia gli errori sostanziali e di contenuto, sia quelli formali e linguistici.
Come sapete, di solito evito di parlare troppo in astratto di quello che le migliori teorie prevedono e suggeriscono, perchè in tal caso il rischio di friggere aria già fritta da altri si fa concreto.
Quindi vi racconto in che modo lavoro io quando devo documentare un prodotto software realizzato nella mia azienda.
Il processo di controllo e validazione nel mio caso prevede 3 figure standard:
- Writer
- Inspector
- Approver
Inspector è usualmente colui che realizza il prodotto; nella letteratura anglosassone è anche indicato come SME (Subject Matter Expert).
Approver è di solito un Supervisore del SME, che è designato quale responsabile tecnico per la progettazione del prodotto.
Il Writer procede sulla base delle sue conoscenze dirette del prodotto e/o dei dati ricavati dalle interviste allo SME. Egli si occupa di definire e rendere facilmente comprensibili tutti gli aspetti funzionali del prodotto, nonchè di curare tutti gli aspetti formali, linguistici, grafici, stilistici e redazionali del documento.
Al termine, sarà compito dell'Inspector verificare che i contenuti del documento siano sostanzialmente congruenti alle caratteristiche tecniche effettive del prodotto. La figura dell'Approver ha il compito della revisione finale che certifica l'effettiva corrispondenza di quanto descritto, anche in funzione del suo ruolo di Supervisore.
Questo schema a 3 livelli si è rivelato semplice ed efficace. Aumentare a dismisura il numero di livelli di controllo non sempre migliora la Qualità del documento mentre è quasi sempre causa di ritardi nel suo rilascio ufficiale.
Tuttavia lo schema può essere "specializzato" al bisogno.
Dal 2008 io scrivo i manuali direttamente in inglese ma ho bisogno di un assistente "madre-lingua" che ripulisca i miei testi da qualche stortura linguistica. Questa figura coincide con quella di un Inspector "specializzato", che può intervenire sia prima che dopo l'Approver e che si occupa esclusivamente di implementare alcune tecniche di proofreading.
Questo semplice workflow prevede quindi 4 figure.
Un processo di questo tipo non assicura l'eliminazione di qualsiasi tipo di errore, ma di certo è in grado di risolvere un gran numero di difetti sostanziali e formali, aumentando senza alcun dubbio la Qualità del documento validato rispetto al documento di partenza. Leggi questo articolo...