Quali documenti... per quale prodotto?

Nel post del 2 Luglio ho fornito una roadmap minima attraverso la quale è possibile pianificare la produzione della documentazione di un'azienda. In funzione del contesto, tale roadmap può essere arricchita e diversificata.
Ma supponendo di partire da zero, gli elementi indicati sono da ritenersi gli elementi di base necessari da cui possiamo partire per organizzare il nostro lavoro.

A questo punto, chiediamoci COSA dobbiamo documentare e QUALI/QUANTI documenti dobbiamo mettere in cantiere a tale scopo.
Io lavoro in un'azienda IT che realizza prodotti software, in un'area di mercato altamente specializzata. Nel mio caso, per documentare un singolo prodotto, è sempre necessario realizzare ALMENO i seguenti documenti:

- BROCHURE: è il documento di marketing che fornisce, al cliente potenziale, le prime informazioni fondamentali sul prodotto.

- TECHNICAL SPECIFICATION: è il documento di sintesi che racchiude tutte le informazioni tecniche necessarie sul prodotto.

- INSTALLATION MANUAL: è il documento che fornisce tutte le informazioni per installare ed eventualmene configurare il prodotto.

- GETTING STARTED MANUAL (QUICK START GUIDE): è il documento che consente di prendere confidenza rapidamente con tutte le funzionalità di base del prodotto.

- ADMINISTRATION MANUAL: è un documento che contiene tutte le informazioni dettagliate, spesso in modalità Tutorial, rivolto ad un utente "evoluto", destinato al ruolo di Amministratore del prodotto e che quindi deve conoscere ogni aspetto del medesimo.

Perchè li ho elencati con la dizione inglese ?
Perchè abbiamo deciso di scrivere la documentazione di prodotto in inglese, visto che il mercato al quale ci rivolgiamo non è limitato all'interno dei confini nazionali.

Poi è spesso necessario mettere a punto altri documenti quali:

- USER MANUAL: è un documento rivolto ad un utente che deve usare il prodotto (tipicamente un sottoinsieme delle funzionalità disponibili nel prodotto) ma non ha le esigenze dell'utente a cui è dedicato l'Administrator Manual.

- INTEGRATION MANUAL: è un documento che descrive in che modo è possibile integrare il prodotto in un'architettura software pre-esistente, o l'aggiornamento del prodotto rispetto ad una versione precedente gia installata nel sistema ospite.

- API REFERENCE MANUAL: è un documento, finalizzato ad un tecnico programmatore, che descrive le librerie software eventualmente associate al prodotto.

Inoltre, all'interno delle applicazioni software, è necessario predisporre un HELP in formato HTML, i cui contenuti possono essere mutuati da uno o più manuali tra quelli elencati ma che richiedono un lavoro di filtro e formattazione che non può essere realizzato attraverso un banale
e meccanico "copia e incolla" di quanto già realizzato.

Ogni singolo prodotto deve poi essere testato e collaudato e questo richiede lo sviluppo di un'appropriata DOCUMENTAZIONE DI COLLAUDO.

C'è tutto? Certamento no... ma c'è abbastanza.

E TUTTO QUESTO PER OGNI SINGOLO PRODOTTO!

Ma se invece di un prodotto software dobbiamo documentare un video-registratore?
In tal caso l'INSTALLATION MANUAL e la QUICK START GUIDE dovrebbero essere sufficenti, almeno per iniziare ad usare il prodotto. Ma deve essere predisposto anche lo USER MANUAL per i clienti più esigenti, che vogliono indagare anche le funzionalità meno comuni.

L'altra settimana ho comprato una piscina di plastica da giardino... di quelle per far giocare i bambini nei giorni più torridi dell'estate; c'era il MANUALE DI MONTAGGIO in forma cartacea ed un CD ROM contenente un filmato di presentazione in formato AVI, in cui sono illustrate
accuratamente tutte le fasi di montaggio e manutenzione.

Insomma, ogni prodotto richiede un set di documenti ben preciso, in base alla sua natura, all'uso che se ne deve fare e a chi lo dovrà utilizzare.

E' ASSOLUTAMENTE NECESSARIO STABILIRE CON ATTENZIONE la manualistica da realizzare per ogni prodotto, nelle diverse forme possibili.

E QUANDO REALIZZIAMO UN PROGETTO PER UN CERTO CLIENTE?

Un progetto si sviluppa attraverso diverse fasi ben distinte; generalmente, ogni fase prevede un certo tipo di documentazione.
Ad esempio, nella fase iniziale di un progetto software, viene redatto il DOCUMENTO DI ASSESSMENT, in cui viene delineata l'analisi del progetto e le soluzioni funzionali richieste, sulla base delle specifiche caratteristiche tecniche e delle logiche di business proprie del cliente,
nonchè di altri vincoli in essere (moduli software/hardware già posseduti dal cliente, prescrizioni legislative, ecc...).

Nella fase finale del progetto, quando l'architettura software viene rilasciata in esercizio, viene prodotto il MANUALE DI ESERCIBILITA', che racchiude tutte le informazioni tecniche necessarie alla gestione dell'architettura.

Se l'architettura prevede l'integrazione di uno più prodotti, dovrà essere rilasciata tutta la necessaria documentazione relativa ad ogni singolo prodotto e l'eventuale sopracitato INTEGRATION MANUAL.

Se poi sono state introdotte delle personalizzazioni "ad-hoc", anche tali moduli personalizzati dovranno essere documentati con manuali dedicati.

Il DOCUMENTO DI ASSESSMENT e il MANUALE DI ESERCIBILITA' possono essere idealmente considerati il documento iniziale e il documento finale di un progetto sofware; lungo lo sviluppo del progetto potranno poi essere rilasciati un gran numero di documenti intermedi.

Analoghe considerazioni possono essere svolte in altri ambiti tecnici.

La DOCUMENTAZIONE DI PROGETTO riveste una sua specificità ed è ancor meno schematizzabile rispetto a quella che dobbiamo sviluppare per un prodotto. La stretta collaborazione tra i diversi progettisti ed il TW, nonchè l'esperienza di tali soggetti nella gestione delle diverse fasi del progetto, sono elementi essenziali per poter sviluppare dei buoni documenti.

In conclusione, spero di avervi convinto, pur non potendo esaurire l'argomento in un singolo post, che la capacità di pianificare COSA si deve fare, PRIMA DI INIZIARE "A FARE", rappresenta il fidato "filo di Arianna" che ci garantisce di non perderci nel labirinto.

Condividi

Articoli correlati per categorie