Istruzioni passo passo gratis 
Se il codice sorgente è particolarmente lungo, può essere documentato sotto forma di un file di aiuto, che può essere indicizzato e ricercato con parole chiave. Questo è un vantaggio particolare per le applicazioni in cui la logica del programma è frammentata su molte pagine e contiene un numero di file aggiuntivi, ad esempio con alcune applicazioni web. Alcuni linguaggi di programmazione, come Java e .NET Framework (Visual Basic.NET, C#), hanno i propri standard per la documentazione del codice. In questi casi, segui gli standard su quanta documentazione dovrebbe essere inclusa nel codice sorgente. 
I programmi di elaborazione testi per Microsoft Word sono sufficienti per creare file di testo separati per la documentazione, purché la documentazione sia abbastanza breve e semplice. Per file di testo lunghi e complessi, molti scrittori tecnici preferiscono uno strumento di documentazione come Adobe FrameMaker. I file della guida per la documentazione del codice sorgente possono essere prodotti con qualsiasi strumento di creazione della guida, come RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare o HelpLogix. 
Guarda le caratteristiche che hanno i tuoi potenziali utenti. È probabile che un amministratore di sistema sia un esperto di una serie di applicazioni software, mentre è probabile che un addetto all`immissione dei dati conosca solo l`applicazione che sta utilizzando per immettere i dati. Guarda gli utenti stessi. Sebbene i titoli di lavoro di solito indichino cosa fanno le persone, possono esserci differenze significative nel modo in cui determinate posizioni vengono ricoperte all`interno di un`organizzazione. Intervistando potenziali utenti puoi avere un`idea se la tua impressione su ciò che indica la loro posizione è corretta o meno. Visualizza la documentazione esistente. La documentazione per le versioni precedenti del software (così come le specifiche funzionali) fornisce un`indicazione di ciò che l`utente deve sapere per utilizzare il programma. Tuttavia, tieni presente che gli utenti finali non sono realmente interessati a come funziona il programma, ma a cosa può fare per loro. Determina le attività che devono essere eseguite per completare un compito e quali attività devono essere eseguite prima che tali attività possano essere eseguite. 
Una guida di riferimento è dedicata alla spiegazione delle singole funzioni di un`applicazione software (pulsanti, schede, campi e finestre di dialogo) e del loro funzionamento. Molti file della guida sono scritti in questo formato, in particolare la guida sensibile al contesto che mostra un argomento rilevante quando un utente fa clic sul pulsante Guida in una determinata schermata. Una guida per l`utente spiega come utilizzare il software per eseguire un`attività particolare. I manuali utente sono spesso formattati come guide stampate o PDF, sebbene alcuni file della guida contengano argomenti su come eseguire determinate attività. (Questi argomenti della guida di solito non dipendono dal contesto, sebbene possano essere collegati ad argomenti che lo sono.) Le guide per l`utente spesso si presentano sotto forma di tutorial, con una panoramica delle attività da svolgere nell`introduzione e istruzioni fornite in passaggi numerati. 
I file della guida e la guida in linea devono essere indicizzati e ricercabili con parole chiave, consentendo agli utenti di trovare rapidamente le informazioni di cui hanno bisogno. Sebbene i costruttori di file della guida possano generare automaticamente indici, spesso è meglio creare l`indice manualmente, utilizzando i termini che gli utenti di solito cercheranno. 
Scrivere documentazione per software
Contenuto
Una buona documentazione del software, sia che si tratti di un documento di specifiche per programmatori e tester, di un documento tecnico per i colleghi o di manuali software e file di aiuto per gli utenti finali, aiuta la persona che deve lavorare con il software a comprenderne tutte le caratteristiche e le funzioni. Una buona documentazione del software è specifica, concisa e pertinente e fornisce tutte le informazioni importanti alla persona che utilizza il software. Di seguito troverai le istruzioni su come scrivere la documentazione del software per utenti tecnici e utenti finali.
Passi
Metodo 1 di 2: scrittura di documentazione software per utenti tecnici
1. Decidi quali informazioni includere. Le specifiche del software fungono da guide per i progettisti dell`interfaccia utente, i programmatori che scrivono il codice e i tester che verificano che il software funzioni come previsto. Le informazioni esatte dipendono dal programma in questione, ma possono includere uno dei seguenti:
- I file più importanti all`interno dell`applicazione. Questi possono essere file creati dal team di sviluppo, database a cui si accede durante il funzionamento del programma e utilità di terze parti.
- Funzioni e sottoprogrammi. Ciò include una spiegazione di ciò che fa ciascuna funzione o subroutine, inclusi tutti i valori di input e output.
- Variabili e costanti del programma e come vengono utilizzate nell`applicazione.
- La struttura generale del programma. Per un`applicazione basata su disco, questa potrebbe essere una descrizione dei singoli moduli e librerie del programma, mentre per un`applicazione Web potrebbe descrivere quali pagine utilizzano quali file.
2. Decidi quanta documentazione deve essere inclusa nel codice del programma e quanta deve essere tenuta separata. Più documentazione tecnica è già stata sviluppata all`interno del codice sorgente del programma, più facile sarà aggiornarla e mantenerla insieme al codice, nonché documentare diverse versioni dell`applicazione originale. Come minimo, la documentazione all`interno del codice sorgente dovrebbe spiegare lo scopo di funzioni, subroutine, variabili e costanti.
3. Scegli lo strumento di documentazione giusto. In una certa misura, ciò è determinato dal linguaggio in cui è scritto il codice (come C++, C#, Visual Basic, Java o PHP), poiché esistono strumenti specifici per questi e altri linguaggi. Negli altri casi, il tipo di documentazione richiesta determina quale strumento utilizzare.
Metodo 2 di 2: scrittura di documentazione software per utenti finali
1. Determina le ragioni commerciali della tua documentazione. Sebbene il motivo funzionale per documentare il software sia aiutare gli utenti a capire come utilizzare l`applicazione, ci sono altri motivi come l`assistenza nella commercializzazione del software, il miglioramento dell`immagine aziendale e, soprattutto, la riduzione dei costi di supporto tecnico. In alcuni casi, la documentazione è necessaria per ottemperare a determinati regolamenti o altri requisiti legali.
- Tuttavia, la documentazione del software non dovrebbe in alcun modo sostituire una progettazione dell`interfaccia scadente. Se un`applicazione richiede pagine di documentazione come guida, è meglio cambiare il design dello schermo in qualcosa di più intuitivo.
2. Comprendi il pubblico per cui stai scrivendo la documentazione. Nella maggior parte dei casi, gli utenti di software hanno poca conoscenza dei computer oltre alle attività che possono eseguire con le applicazioni che utilizzano. Esistono diversi modi per determinare di cosa hanno bisogno e come la tua documentazione può soddisfarli.
3. Determinare il formato corretto per la documentazione. La documentazione del software può essere strutturata in 1 di 2 formati: il manuale e il manuale utente. A volte una combinazione di entrambi i formati è l`approccio migliore.
4. Decidi quale forma deve assumere la documentazione. La documentazione del software può assumere molte forme: manuali, documenti PDF, file della guida o guida in linea. Ogni modulo è progettato per mostrare all`utente l`uso di ciascuna delle funzionalità del programma, sia sotto forma di procedura dettagliata che di tutorial; nel caso dei file della guida e della guida in linea, può trattarsi di testo, video dimostrativi e immagini.
5. Scegli uno strumento di documentazione adatto. I manuali stampati o PDF possono essere scritti utilizzando un programma di elaborazione testi come Word o un editor di testo avanzato come FrameMaker, a seconda della loro lunghezza e complessità. I file della guida possono essere scritti con uno speciale strumento di authoring come RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix o HelpServer.
Consigli
- Il testo dovrebbe essere organizzato in modo da essere di facile lettura, con immagini il più vicino possibile al testo a cui si riferisce. Dividi logicamente la documentazione in paragrafi, sezioni e argomenti. Ogni paragrafo o argomento deve spiegare un singolo problema, sia esso una singola funzione del programma o un`attività. I problemi correlati possono essere spiegati, ove appropriato, utilizzando elenchi o collegamenti ipertestuali "Vedi anche" come indicato sopra.
- Qualsiasi degli strumenti di documentazione sopra elencati può essere integrato con un programma di screenshot, come Snagit, se la documentazione richiede alcuni screenshot. Come con altra documentazione, dovrebbero essere inclusi screenshot per aiutare a spiegare come funziona il software, per non confondere l`utente.
- Il tono è molto importante, soprattutto quando si scrive documentazione software per gli utenti finali. Indirizzare gli utenti in seconda persona ("tu") anziché in terza persona ("utente").
Necessità
- Utilità di documentazione software/file di aiuto
- Utilità screenshot
Articoli sull'argomento "Scrivere documentazione per software"
Condividi sui social network:
Popolare
