Una buona documentazione del software, che si tratti di documentazione delle specifiche per programmatori e tester, documenti tecnici per utenti interni o manuali e file della guida per gli utenti finali, aiuterà gli utenti a comprendere le caratteristiche e le funzioni del software. Una buona documentazione è una documentazione specifica, chiara e pertinente, con tutte le informazioni di cui l'utente ha bisogno. Questo articolo ti guiderà nella scrittura della documentazione del software per gli utenti tecnici e gli utenti finali.
Fare un passo
Metodo 1 di 2: Scrittura di documentazione software per utenti tecnici
Passaggio 1. Sapere quali informazioni includere
Il documento delle specifiche viene utilizzato come manuale di riferimento per progettisti di interfacce, programmatori che scrivono codice e tester che verificano le prestazioni del software. Le informazioni che devono essere incluse dipenderanno dal programma in fase di creazione, ma possono includere quanto segue:
- File importanti nell'applicazione, come file creati dal team di sviluppo, database a cui si accede mentre il programma è in esecuzione e applicazioni di terze parti.
- Funzioni e sottoprogrammi, inclusa una spiegazione dell'uso della funzione/sottoprogramma, valori di ingresso e di uscita.
- Variabili e costanti di programma e come vengono utilizzate.
- Struttura generale del programma. Per i programmi basati su unità, potrebbe essere necessario descrivere ogni modulo e libreria. Oppure, se stai scrivendo un manuale per un programma basato sul web, potresti dover spiegare quali file utilizza ciascuna pagina.
Passaggio 2. Decidere quale livello di documentazione dovrebbe essere presente e separabile dal codice del programma
Più documentazione tecnica è inclusa nel codice del programma, più facile sarà aggiornarla e mantenerla, oltre a spiegare le diverse versioni del programma. Come minimo, la documentazione nel codice del programma dovrebbe includere l'uso di funzioni, subroutine, variabili e costanti.
- Se il tuo codice sorgente è lungo, puoi scrivere la documentazione in un file di aiuto, che può quindi essere indicizzato o ricercato con determinate parole chiave. I file di documentazione separati sono utili se la logica del programma è suddivisa su più pagine e include file di supporto, come un'applicazione Web.
- Alcuni linguaggi di programmazione (come Java, Visual Basic. NET o C#) hanno i propri standard di documentazione del codice. In tali casi, seguire la documentazione standard che deve essere inclusa nel codice sorgente.
Passaggio 3. Selezionare lo strumento di documentazione appropriato
In alcuni casi, lo strumento di documentazione è determinato dal linguaggio di programmazione utilizzato. I linguaggi C++, C#, Visual Basic, Java, PHP e altri hanno i propri strumenti di documentazione. Tuttavia, in caso contrario, gli strumenti utilizzati dipenderanno dalla documentazione richiesta.
- Un elaboratore di testi come Microsoft Word è adatto per creare file di testo di documenti, purché la documentazione sia concisa e semplice. Per creare una documentazione lunga con testo complesso, la maggior parte degli scrittori tecnici sceglie uno strumento di documentazione specializzato, come Adobe FrameMaker.
- I file di aiuto per documentare il codice sorgente possono essere creati con un programma di generazione di file di supporto, come RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare o HelpLogix.
Metodo 2 di 2: scrittura della documentazione del software per gli utenti finali
Passaggio 1. Conoscere le ragioni aziendali alla base della creazione del manuale
Sebbene il motivo principale per la documentazione del software sia quello di aiutare gli utenti a capire come utilizzare l'applicazione, ci sono molti altri motivi che possono essere alla base della creazione della documentazione, come aiutare il reparto marketing a vendere l'applicazione, migliorare l'immagine dell'azienda e ridurre il supporto tecnico costi. In alcuni casi, la documentazione è richiesta per conformarsi a regolamenti o altri requisiti legali.
Tuttavia, la documentazione non è un buon sostituto di un'interfaccia. Se un'applicazione richiede molta documentazione per funzionare, dovrebbe essere progettata per essere più intuitiva
Passaggio 2. Conoscere il pubblico di destinazione della documentazione
In genere, gli utenti di software hanno una conoscenza informatica limitata oltre alle applicazioni da loro utilizzate. Esistono diversi modi per soddisfare le loro esigenze di documentazione:
- Prestare attenzione al titolo dell'utente del software. Ad esempio, l'amministratore di sistema generalmente comprende varie applicazioni informatiche, mentre la segretaria conosce solo le applicazioni che utilizza per inserire i dati.
- Presta attenzione agli utenti del software. Sebbene le loro posizioni siano generalmente compatibili con le attività svolte, queste posizioni possono avere carichi di lavoro diversi, a seconda della sede dell'attività. Intervistando potenziali utenti, puoi scoprire se la tua valutazione del loro titolo di lavoro è corretta.
- Prestare attenzione alla documentazione esistente. La documentazione e le specifiche delle funzionalità del software possono mostrare ciò che gli utenti devono sapere per utilizzarli. Tuttavia, tieni presente che gli utenti potrebbero non essere interessati a conoscere "l'interno" del programma.
- Sapere cosa serve per completare un'attività e cosa serve prima di poterla completare.
Passaggio 3. Determinare il formato appropriato per la documentazione
La documentazione del software può essere organizzata in 1 o 2 formati, vale a dire libri di riferimento e manuali. A volte, combinare i due formati è una buona soluzione.
- I formati di riferimento vengono utilizzati per descrivere tutte le funzionalità del software, come pulsanti, schede, campi e finestre di dialogo, e come funzionano. Alcuni file della guida sono scritti in questo formato, specialmente quelli sensibili al contesto. Quando l'utente fa clic su Guida in una determinata schermata, riceverà l'argomento pertinente.
- Il formato manuale viene utilizzato per spiegare come fare qualcosa con il software. I manuali sono generalmente in formato cartaceo o PDF, sebbene alcune pagine di aiuto includano anche istruzioni su come eseguire determinate operazioni. (In genere, i formati manuali non sono sensibili al contesto, ma possono essere collegati da argomenti sensibili al contesto). I manuali sono generalmente sotto forma di guida, con un riepilogo delle attività da svolgere in una descrizione e una guida formattata in passaggi.
Passaggio 4. Decidi il tipo di documentazione
La documentazione del software per gli utenti può essere fornita in uno o più dei seguenti formati: manuali stampati, file PDF, file della guida o guida in linea. Ogni tipo di documentazione è progettata per mostrarti come utilizzare le funzioni del software, che si tratti di una guida o di un tutorial. La documentazione in linea e le pagine della guida possono includere anche video dimostrativi, testo e immagini statiche.
I file della guida in linea e del supporto devono essere indicizzati e ricercabili utilizzando parole chiave in modo che gli utenti possano trovare rapidamente le informazioni di cui hanno bisogno. Sebbene un'applicazione per la generazione di file della guida possa creare automaticamente un indice, si consiglia comunque di creare un indice manualmente utilizzando le parole chiave comunemente cercate
Passaggio 5. Selezionare lo strumento di documentazione appropriato
Manuali stampati o PDF possono essere creati con un programma di elaborazione testi come Word o un editor di testo avanzato come FrameMaker, a seconda della lunghezza e della complessità del file. I file di aiuto possono essere scritti con un programma di creazione di file di aiuto, come RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix o HelpServer.
Suggerimenti
- Il testo della documentazione del programma dovrebbe essere strutturato in modo tale da essere di facile lettura. Posiziona l'immagine il più vicino possibile al testo appropriato. Suddividi la documentazione per sezioni e argomenti in modo logico. Ogni sezione o argomento dovrebbe descrivere un problema specifico, sia l'attività che le funzionalità del programma. I problemi correlati possono essere spiegati con collegamenti o elenchi di riferimento.
- Ciascuno degli strumenti di documentazione descritti in questo articolo può essere integrato da un programma per la creazione di screenshot, come SnagIt se la documentazione richiede più screenshot. Come qualsiasi altra documentazione, dovresti anche includere schermate per aiutare a spiegare come funziona l'app, piuttosto che "attirare" l'utente.
- Prestare attenzione allo stile è molto importante, soprattutto se si scrive documentazione software per gli utenti finali. Rivolgiti agli utenti con il pronome "tu", invece di "utente".
