In breve: Il manuale utente guida chi usa un prodotto. La documentazione tecnica spiega come funziona dentro.
A cosa serve la documentazione
Quando creiamo un software, dobbiamo spiegarlo a chi lo userà. Senza spiegazioni, anche un buon programma diventa inutile.
Esistono due tipi principali di documenti. Il manuale utente è scritto per chi usa il prodotto. La documentazione tecnica è scritta per chi sviluppa o mantiene il prodotto.
Pensa al libretto della lavatrice. Una parte ti dice quali tasti premere. Un'altra parte, più nascosta, serve al tecnico che la ripara.
Le parti del manuale utente
Un manuale utente ben fatto segue di solito una struttura ordinata. Le sezioni aiutano il lettore a trovare subito ciò che cerca.
La copertina mostra il titolo, la versione del prodotto e la data. L'indice elenca i capitoli con i numeri di pagina. L'introduzione spiega a chi è rivolto il manuale e cosa contiene.
Segue la sezione di installazione o primo avvio. Poi vengono le istruzioni d'uso, divise per funzioni. Alla fine si trovano la risoluzione dei problemi e i contatti per l'assistenza.
Il linguaggio deve essere semplice. Le immagini e gli screenshot aiutano a capire meglio.
Le parti della documentazione tecnica
La documentazione tecnica è più dettagliata. Si rivolge a programmatori, tecnici o futuri sviluppatori del progetto.
Contiene la descrizione dell'architettura del software. Spiega i moduli, le loro funzioni e come comunicano tra loro. Include schemi, diagrammi e specifiche delle interfacce.
Una parte importante è la documentazione del codice. Servono i commenti dentro il codice e i documenti che descrivono le funzioni principali. Si aggiungono anche le istruzioni per installare l'ambiente di sviluppo.
Esempi pratici
Immagina di scrivere un'app per ordinare la pizza. Il manuale utente spiegherà come scegliere gli ingredienti e pagare. Userà frasi semplici e immagini dei pulsanti.
La documentazione tecnica, invece, descriverà come l'app si collega al database. Spiegherà la funzione che calcola il prezzo. Mostrerà lo schema dei dati salvati.
Un altro esempio: il sito di una scuola. Gli utenti leggono come iscriversi. Gli sviluppatori leggono come è costruito il sistema di login.
Per scrivere bene, segui questi passaggi. Definisci prima il lettore. Scegli un ordine logico per i capitoli. Usa esempi e immagini. Rileggi e fai provare il manuale a una persona nuova.
Parole difficili
- Manuale utente: documento che spiega come usare un prodotto.
- Documentazione tecnica: insieme di documenti rivolti a sviluppatori e tecnici.
- Architettura: organizzazione interna di un software e dei suoi componenti.
- Modulo: parte di un programma che svolge una funzione specifica.
- Screenshot: immagine che mostra ciò che appare sullo schermo.
- Interfaccia: punto di contatto tra utente e programma, o tra due programmi.
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.interventi-implementazione.11