Spesso pieni di gergo, acronimi e indicazioni che richiedono un Ph.D per capire, i manuali utente del software sono talvolta scritti dal punto di vista di uno sviluppatore piuttosto che da un utente. Di conseguenza, la guida può formulare ipotesi sul livello di abilità del lettore che sono spesso errate. Il primo passo per scrivere un buon manuale utente è quello di ottenere il processo di scrittura reale il più lontano possibile dagli ingegneri.
Lo sviluppatore del software sa più di chiunque altro che funzioni il software, ma ciò non significa che lo sviluppatore debba scrivere la guida. Al contrario, è un netto svantaggio. Più importante di una profonda comprensione del funzionamento interno del software è la comprensione di chi sarà l'utente finale, qual è il suo livello di istruzione e in che modo l'utente finale utilizzerà il software. Nella maggior parte dei casi, gli utenti finali non hanno bisogno di conoscere i punti più fini della programmazione e del funzionamento back-end del software - hanno solo bisogno di sapere come usarlo per rendere più facile il loro lavoro.
Test utente
Il manuale utente dovrebbe essere in gran parte orientato alle attività, piuttosto che fortemente descrittivo. Poiché il manuale è scritto per aiutare gli utenti a capire come eseguire attività specifiche, lo scrittore deve avere una comprensione di tali compiti e, di conseguenza, è assolutamente essenziale passare attraverso ogni fase discreta di ciascuna funzionalità. Non è necessario che lo scrittore sappia necessariamente come il programma è stato creato da un punto di vista del design o dello sviluppo, ma è essenziale avere una forte conoscenza operativa di tutte le sue funzionalità. Durante l'esecuzione di ciascuna attività, dedica del tempo a scrivere ogni singolo passaggio, inclusi clic, menu a discesa e altre azioni.
Il processo dell'intervista
Sebbene lo sviluppatore non debba essere il solo a scrivere il manuale, sarà comunque una risorsa preziosa per lo scrittore e, prima di iniziare a scrivere, pianificare un incontro preliminare tra lo scrittore, lo sviluppatore e gli ingegneri e potenziali utenti finali per aiutare a informare il lavoro dello scrittore dall'inizio. Le interviste con esperti in materia e ingegneri dovrebbero essere registrate, con trascrizioni fatte per riferimento futuro.
Immagini
Un manuale utente non dovrebbe essere troppo pesante per il testo. Piuttosto, incorporare l'uso liberale di grafica e clip sullo schermo. La descrizione di un'azione è molto più chiara con indicazioni basate sul testo accompagnate da una clip che illustra chiaramente quella direzione. Includere sia prima che dopo le visualizzazioni, per mostrare come appare lo schermo prima di eseguire ogni azione e cosa succede dopo che l'azione è stata eseguita. Una semplice utility di cattura dello schermo come lo Snipping Tool incluso in Microsoft Windows funziona bene per catturare queste immagini. Assicurati di numerare ciascuna immagine e includi una didascalia che la descriva brevemente. Centra immediatamente sotto il paragrafo che introduce per la prima volta il concetto rappresentato nell'immagine.
formattazione
Comunicare chiaramente in un documento tecnico richiede una pianificazione e un'attenta osservanza degli standard in tutta la guida. Gli standard di presentazione, lingua e nomenclatura aiutano a evitare confusione. I modelli sono disponibili e possono essere un buon punto di partenza per l'uniformità, sebbene questi possano certamente essere adattati per adattarsi a ciascuna situazione. L'utilizzo di un margine di un pollice con una singola colonna si adatta meglio alla necessità di aggiungere elementi grafici; un'impostazione a due colonne potrebbe apparire troppo affollata e rendere confusa la collocazione di immagini.
Versioning e tracciamento
Più di ogni altro tipo di documento, è probabile che una guida utente del software passi attraverso più iterazioni prima che sia completa ed è probabile che passi attraverso un processo di revisione da parte di più parti interessate. L'utilizzo della funzionalità Revisioni di Microsoft Word è un modo semplice per tenere traccia dei commenti e delle modifiche di ogni individuo. La creazione di più versioni dopo ogni ciclo di revisione, ognuna con un nome file diverso, aiuta anche il processo e assicura che tutti gli stakeholder siano soddisfatti del risultato finale.
