All'inizio di un nuovo lavoro, o in quello attuale, quando siamo catapultati in un progetto per software di gestione documentale già avviato, si è spesso travolti da un ritmo che non si riesce a tenere. Questo articolo vi suggerisce come valutare la situazione, sviluppare un piano e cominciare a scrivere rapidamente.

Studiate lo scenario

Innanzitutto, dovete scoprire il background del progetto – il suo stato, il team e gli standard impiegati per la documentazione.

Stato del Progetto

La maggior parte dei progetti per software rientrano in una delle sette categorie seguenti:

• Un nuovo prodotto ancora in fase di sviluppo, senza documentazione utente
• Un nuovo prodotto completo (o prossimo al completamento), senza documentazione utente
• Un prodotto esistente con documentazione limitata
• Un prodotto esistente con documentazione
• Un prodotto esistente in via di trasferimento a una nuova interfaccia utente o sottoposto ad altri cambiamenti significativi
• Un prodotto esistente in manutenzione/di cui si sta elaborando una nuova versione
• Prodotto esistente in manutenzione

Dovete scoprire a quale categoria corrisponde il progetto e quali sono le specifiche o i requisiti esistenti (se del caso). Verificate con gli esperti in materia (SME) l'aggiornamento di tali documenti.
Se esiste una documentazione per l'utente finale, dovrete revisionarla nella fase di programmazione, dopo aver determinato quali sono i prodotti finali e gli argomenti di cui avete bisogno. A questo punto saprete cosa manca e quali argomenti devono essere riorganizzati o ristrutturati.

Il team

Ci sono molte cose importanti che dovete conoscere sul vostro team, oltre a sapere chi ne fa parte: dovete identificare gli SME, sapere chi sono gli SME al di fuori del team e qual è la metodologia di sviluppo software in uso.
Per "team" intendo il gruppo polifunzionale che lavora al progetto e non il gruppo a cui appartenete all'interno della struttura organizzativa. Il project team potrebbe riunire alcune delle seguenti figure: project manager, product manager, business analyst, personale impiegato nel reparto garanzia della qualità, staff tecnico di supporto, sviluppatori software. È importante scoprire rapidamente gli SME e informarli sul ruolo che rivestite nell'ambito del progetto.
Esistono diverse metodologie per lo sviluppo dei software. Il modello Agile e quello a cascata (Waterfall) sono i più comuni, ma entrambi hanno diverse variazioni, e ciascuna di esse racchiude diverse filosofie. Scoperta la metodologia impiegata, imparate il più possible su di essa (se non la conoscete già), ma ricordate che difficilmente una metodologia viene seguita alla lettera. Dovete scoprire le diversificazioni e regolarvi di conseguenza. Potreste anche trovarvi in un team che non mette alcuna etichetta sul proprio processo. In questo caso, decifrare a che punto del processo inserirvi potrebbe richiedere più tempo.

Standard

Un progetto documentale ha bisogno di standard. Stabilire quelli del vostro progetto – o individuare quelli già utilizzati dalla vostra azienda o dal progetto stesso e documentarli, può farvi risparmiare tempo. Una guida di stile interno, se esistente, costituisce uno strumento prezioso, ma a volte non contiene i seguenti standard (se non li contiene, aggiungeteli quando vi è possibile): template di progetto/CSS attuali e loro posizione; metodo controllo versione; chi fornisce gli ID di contesto per la guida context-sensitive; le regole relative a screencap e grafica (tipo di file, DPI, stile dei callout, ecc.); requisiti video (tipo uscita, durata, audio, stile didascalie, informazioni boilerplate di apertura/chiusura). Avere una copia del Manuale di Microsoft a portata di mano risulta utile.
Altri standard riguardano i vostri strumenti: Help Authoring Tool (HAT), screen capture, creazione video, ecc. Se non disponete degli strumenti di cui avete bisogno, stabilite quail sono le funzioni necessarie e iniziate a indagare. HAT-Matrix costituirebbe un buon inizio: http://hat-matrix.com/ 

Dopo lo studio … la programmazione

Una volta recuperate le informazioni sul trascorso, potete programmare e iniziare a scrivere. Una programmazione preventiva consente di risparmiare tempo nella fase di scrittura, perché avete documentato e organizzato ciò che vi occorre, e avete stabilito come dovrebbe essere strutturato.
Se il prodotto al momento ha già una documentazione per l'utente, potete utilizzare quanto segue per stabilire se bisogna riscriverla o ristrutturarla, cosa manca e se sono necessari altri prodotti.

Scegliete i prodotti

Decidete quali prodotti includere. Elencate tutto, anche ciò che sarà rilasciato in futuro. L'elenco potrebbe includere quanto segue: guida online, manuali, guide rapide, video, appunti, informazioni guida, articoli per una conoscenza di base, tooltip/tooltip estesi e altro ancora.
Al momento della scelta dei prodotti, non dimenticate quanto segue:

• L'ambiente di lavoro degli utenti finali ha delle limitazioni e quali? (riscontrabile con osservazione/ricerca sul campo e con l'aiuto degli SME)
• Quail sono le preferenze degli utenti finali in tema di informazione?
• Questo rilascio avviene in circostanze speciali? (Ad esempio una nuova interfaccia. In questo caso, potrebbe risultare necessario aggiungere delle guide rapide per illustrare i cambiamenti agli utenti esistenti.)
• Contributi degli SME

Stabilite inoltre:

• Quali saranno le uscite per ogni prodotto? (Ad esempio, potrebbe essere necessaria sia una guida HTML che una Web-based.)
• Sono necessarie versioni diverse dello stesso prodotto da destinare a categorie di pubblico diverse? (Ad esempio, una guida utente diversa per il farmacista, la capo infermiera, e l'infermiera.)
• Come saranno nominati i file di ciascun prodotto? Ottenete l'approvazione per ciscuno. Modificare il nome dei file all'ultimo minuto può comportare errori (gli script di installazione e i collegamenti ipertestuali potrebbero scollegarsi.) Se possibile, nei nomi non si dovrebbe inserire l'anno.
• Dove verranno conservati i prodotti? Internamente per le versioni di installazione e sul Web; sul Web dovreste inserire il maggior numero di contenuti possibile – sono più facili da rintracciare, si può pubblicare continuamente ed è il modo più efficace per fare collegamenti – soprattutto video (a causa della loro dimensione, questi file risultano difficili da inserire in fascicoli). Naturalmente, prodotti altamente sensibili non possono essere conservati sul Web, a meno che la vostra azienda non abbia una speciale area protetta (firewall) dedicata ai consumatori.
• Come si effettuerà l'accesso dall'interfaccia? Ci saranno un menu guida e dei tasti? Ci sarà una guida context-sensitive sulle finestre di dialogo? Il prodotto potrebbe essere reso disponibile direttamente dalla pagina di avvio dell'applicazione? Più è facile reperire la documentazione più è probabile che venga reperita.
• Qual è la strategia di social media per il software? Se la vostra azienda è presente su Twitter, Facebook, LinkedIn, o su qualsiasi altro social media, potreste prendere in considerazione la creazione di una community per raccogliere commenti sulla documentazione, pubblicare annunci, o per altri scopi. Se la vostra azienda non è presente sui social media, potreste prendere in considerazione lo sviluppo e l'attuazione di una strategia di documentazione.

Dividete e conquistate

Gli argomenti cardine del vostro progetto — la Guida online e/o il manuale — ricadono all'interno di quattro categorie:

1. Funzionalità (ciò che il software fa; in che modo risolve i problemi dell'utente),
2. Operazioni di routine (requisiti di sistema, accordo di licenza con l'utente finale, istruzioni per l'installazione),
3. Referimenti (glossari, esercitazioni), e
4. Interfaccia Utente (IU); questi argomenti rientrano in quelli relativi alla Funzionalità e includono informazioni che saranno accessibili direttamente dall'IU – quali: guida context-sensitive sulle finestre di dialogo, riquadro Guida integrato, ecc.

Determinate quail argomenti (esistenti e non) appartengono a ciascuna categoria e conservate questa informazione su un foglio elettronico, oppure utilizzate qualsiasi metodo di vostra preferenza.
Visualizzare gli argomenti così raggruppati renderà più facile nominarli con una certa logica e coerenza, nonché individuare una eventuale terminologia interna.
Successivamente sviluppate (o adottate) delle "architetture per argomento". Sono così chiamati quei metodi predefiniti per la strutturazione dei vostri argomenti. Potete creare le vostre, o utilizzare quelle già esistenti. Stabilite di quali architetture avrete bisogno (ad esempio argomenti come: Panoramica sulla funzionalità, Finestra di dialogo) e abbozzate la struttura di ciascuna. L'uso delle architetture rende molto più facile la fase di scrittura perchè vi permette di conoscere cosa richiede ciscun argomento e quindi permette di evitare informazioni ridondanti tra i diversi argomenti e impedisce di omettere involontariamente informazioni che invece sono importanti.
Esempio: Argomento Introduzione alla Funzionalità
Questa architettura viene utilizzata per qualsiasi argomento di introduzione a un pezzo principale sulla funzionalità del prodotto.
Requisiti:

• Titolo
• "Perché è importante?"
• Panoramica
• "Come fare per"/Processi
• Video (se disponibile)
• Argomenti correlati (Generati da HAT + ulteriori aggiunte)

Sviluppate l'architettura del vostro progetto

A questo punto potete organizzare tutti i vostri argomenti e creare l'architettura del vostro progetto. Iniziate dai vostri "cesti" di informazioni (Funzionalità, Operazioni di routine, Referimenti e Interfaccia Utente). Ordinateli in un indice logico; contrassegnate gli argomenti che costituiscono anche la guida context-sensitive per le finestre di dialogo.
Il progetto può avere più di una architettura, soprattutto se da un'unica sorgente vi indirizzate verso uscite diverse per le condizioni d'uso. Anche in tal caso, dovreste iniziare con un'architettura che comprende tutto e quindi contrassegnare solo quegli argomenti che appartengono a specifiche uscite.

Scrivete e consegnate

Dato che conoscete il trascorso del progetto e avete un programma, potete cominciare a scrivere i vostri argomenti, suggerimenti, esercitazioni, guide rapide e altri prodotti e creare video, podcast e altri media.
La forza di un'analisi progettuale condotta in questo modo sta nel fatto che essa è valida sia per i progetti in essere che per quelli nuovi. Non dovete gettar via argomenti e prodotti già esistenti; dovete semplicemente stabilire quale sia la loro collocazione migliore all'interno del progetto e quali variazioni apportare.

Nicky Bleiel è Lead Information Developer alla Doc-To-Help. Ha 15 anni di esperienza in comunicazione tecnica; progettazione e redazione di materiale informativo su prodotti software, nelll'industria della documentazione, media, automazione industriale, simulazione e farmaceutica. È Director at Large della Society for Technical Communication.
nickyb(at)componentone.com
www.doctohelp.com
Blog: "Technical Communication Camp"