In breve: Il manuale utente spiega come usare un prodotto. La documentazione tecnica descrive come funziona dentro.
A cosa serve un manuale
Ogni software ha bisogno di istruzioni chiare per chi lo usa. Senza istruzioni, anche un buon programma diventa difficile.
Pensa a quando compri un forno nuovo. Dentro la scatola trovi un libretto. Quel libretto ti dice come accenderlo e cuocere una pizza.
Per il software vale la stessa regola. Esistono però due tipi di documenti diversi. Uno è per l'utente finale. L'altro è per i tecnici e gli sviluppatori.
Cosa contiene il manuale utente
Il manuale utente parla a chi non conosce la parte tecnica. Usa un linguaggio semplice e immagini.
Di solito contiene queste parti:
- una breve presentazione del prodotto
- i requisiti minimi del computer
- la guida all'installazione passo passo
- le funzioni principali con schermate
- la sezione domande frequenti (FAQ)
- i contatti per l'assistenza
Le frasi sono corte. Spesso ci sono elenchi numerati. Gli screenshot aiutano a capire dove cliccare.
Cosa contiene la documentazione tecnica
La documentazione tecnica è più dettagliata. Serve a chi sviluppa, installa o ripara il software.
Trovi informazioni come:
- l'architettura del sistema
- le API e i parametri delle funzioni
- il modello del database
- le procedure di configurazione del server
- i log degli errori e come leggerli
- le note di versione (changelog)
Qui il linguaggio è più tecnico. Si usano schemi, diagrammi e righe di codice.
Esempi pratici
Immagina un'app di messaggistica. Il manuale utente spiega come inviare una foto a un amico.
La documentazione tecnica spiega invece come l'app cifra il messaggio. Spiega anche quali server riceve la richiesta.
Un altro esempio è un gestionale per negozi. Il manuale mostra come emettere uno scontrino. La documentazione tecnica indica come collegare la stampante fiscale via porta USB.
Quando scrivi un documento, chiediti sempre: chi lo leggerà? Questa domanda guida le scelte di stile e contenuto.
Parole difficili
- API: insieme di comandi che permettono a due programmi di comunicare tra loro.
- FAQ: domande frequenti con relative risposte, raccolte in una lista.
- Changelog: elenco delle modifiche fatte tra una versione e l'altra.
- Screenshot: immagine che mostra ciò che appare sullo schermo in un momento preciso.
- Architettura: struttura generale del software e dei suoi componenti principali.
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.12