In breve: La documentazione spiega come funziona un programma. Va scritta con cura e poi controllata.
Cosa è la documentazione
La documentazione è l'insieme dei testi che accompagnano un software. Serve a chi usa il programma e a chi lo sviluppa.
Senza documentazione, un programma diventa difficile da capire. Anche chi lo ha scritto può dimenticare i dettagli dopo qualche mese.
Esistono due tipi principali di documentazione. Quella per l'utente finale spiega come usare il programma. Quella tecnica spiega come è fatto il codice dentro.
Come si scrive
Una buona documentazione usa frasi brevi e chiare. Ogni funzione del programma viene descritta con il suo scopo.
Per il codice si scrivono i commenti vicino alle righe importanti. I commenti spiegano perché una parte è stata scritta così.
Il manuale utente contiene di solito queste parti:
- introduzione al programma
- requisiti del computer
- guida all'installazione
- istruzioni d'uso passo passo
- soluzioni ai problemi comuni
Ogni parametro di una funzione va descritto. Si indicano il nome, il tipo di dato e cosa rappresenta.
Come si verifica
Verificare significa controllare che la documentazione sia corretta. Una documentazione sbagliata confonde chi la legge.
Si controllano tre aspetti principali. La completezza indica se sono spiegate tutte le parti del software. La chiarezza riguarda la facilità di lettura. L'aggiornamento verifica che i testi corrispondano alla versione attuale del programma.
Esempio pratico: hai modificato il pulsante "Salva" del tuo programma. Devi aggiornare anche la schermata mostrata nel manuale. Altrimenti l'utente vede cose diverse e si perde.
Un metodo utile è far leggere la guida a un compagno. Se riesce a usare il programma senza domande, la documentazione funziona.
Parole difficili
- Documentazione: insieme di testi che spiegano un software.
- Commento: nota scritta nel codice, ignorata dal computer.
- Parametro: valore che una funzione riceve per lavorare.
- Manuale utente: guida scritta per chi usa il programma.
- Verifica: controllo per scoprire errori o parti mancanti.
- Versione: stato del software in un dato momento dello sviluppo.
Riferimenti
- Norma: Norme generali e livelli essenziali delle prestazioni relativi al secondo ciclo del sistema educativo di istruzione e formazione
- Obiettivo formativo coperto: ob.iefp-tecnico-informatico.competenze-tecnico-professionali.cl3.prodotti-comunicazione.03