GUIDA · SOFTWARE E INTEGRAZIONE

Scrivere le specifiche di un software: requisiti che gli sviluppatori capiscono

In questa guida imparerai a scrivere un documento di requisiti che uno sviluppatore può leggere senza fare domande continue. Vedrai come separare cosa il software deve fare da come deve comportarsi, come descrivere un processo con scenari concreti e come verificare, prima di firmare, che il documento sia completo.

Aggiornata a ottobre 2026
8 min di lettura
Redazione Tecnica Altovar

1. Perché un buon documento di requisiti fa risparmiare tempo

Un documento di requisiti è il patto di comprensione tra chi usa il processo e chi lo costruisce. Quando è vago, lo sviluppatore riempie i vuoti con supposizioni, e le supposizioni emergono solo in collaudo, quando correggerle costa di più. Un documento chiaro non elimina le sorprese, ma le riduce e le rende visibili prima che il lavoro sia fatto.

Non serve un documento lungo. Serve un documento verificabile: ogni affermazione deve poter essere controllata da qualcuno che conosce il processo. Il lettore ideale è un responsabile di area che non è tecnico e uno sviluppatore che non ha mai visto la tua azienda. Se una frase non si può controllare, va riscritta con un esempio o con un criterio concreto.

2. Requisiti funzionali e non funzionali

I requisiti funzionali descrivono cosa il software deve fare: creare un ordine, approvare una spesa, generare un documento. I requisiti non funzionali descrivono come deve comportarsi: chi può accedere, quanto deve essere disponibile, come registra le operazioni, quali dati conserva e per quanto tempo. Molti progetti scrivono bene le funzioni e dimenticano le seconde, che però determinano sicurezza, conformità e costi di gestione.

Per i requisiti non funzionali indica l'obiettivo e il motivo, non solo la tecnologia. Scrivi, ad esempio, che solo il personale amministrativo deve poter modificare i prezzi e che ogni modifica va tracciata con utente e data. Lo sviluppatore sceglie come realizzarlo. Questo tiene la specifica leggibile e non la lega a una soluzione che potrebbe cambiare. Basta un esempio concreto per ogni requisito non funzionale.

3. Descrivere un processo con scenari

Il modo più efficace per spiegare una funzione è raccontare uno scenario reale: chi inizia, cosa fa, cosa risponde il software, cosa succede in caso di errore. Uno scenario ha un attore, un obiettivo, un flusso principale e alcune varianti. Ad esempio, la registrazione di una richiesta di assistenza parte da un cliente che chiama, passa dalla verifica dell'anagrafica e si chiude con l'assegnazione a un tecnico.

Per ogni scenario descrivi anche le eccezioni: cosa succede se il dato manca, se il cliente non esiste, se l'approvatore è assente. Le eccezioni sono la parte che gli sviluppatori chiedono più spesso. Scrivile con la stessa cura dello scenario principale, perché è lì che il software fa più danni se è costruito male. Scrivile anche per le regole che bloccano l'operazione.

4. Come scrivere un singolo requisito

Ogni requisito deve avere una forma ripetibile: chi, cosa, quando e con quale verifica. Una frase come 'il sistema deve gestire gli ordini' non è verificabile. Una frase come 'il responsabile vendite può annullare un ordine non ancora spedito, e il sistema registra motivo e utente' lo è. Usa un identificativo stabile per ciascun requisito, così che possa essere citato in verbali, collaudi e richieste di modifica.

Un metodo pratico consiste nel completare, per ogni funzione, sempre gli stessi passi. Il risultato è una scheda di poche pagine per funzione che lo sviluppatore può leggere in autonomia e che il responsabile può controllare senza strumenti tecnici. Non saltare i passi perché sembrano ovvi: sono proprio quelli che mancano più spesso. Indica anche il responsabile di ciascun requisito e la sua data.

  1. Scrivi in una frase l'obiettivo di chi usa la funzione.
  2. Descrivi il flusso principale in passi brevi, uno per riga.
  3. Aggiungi le eccezioni più probabili e cosa deve succedere in ciascuna.
  4. Indica chi può eseguire l'operazione e chi la approva.
  5. Definisci il criterio con cui verificherai il risultato.

5. Dati e regole di business

Le regole di business sono le decisioni del tuo lavoro che il software deve rispettare: un prezzo che dipende dal cliente, una scadenza che cambia con il tipo di documento, un'approvazione richiesta sopra una certa soglia. Vanno scritte in modo esplicito, con l'origine della regola. Se la regola dipende da una norma o da un contratto, indica il documento di riferimento e chi lo ha verificato.

Il dizionario dei dati è spesso dimenticato, ma è il documento che evita più discussioni in fase di sviluppo. Definisce ogni campo, il formato, i valori ammessi, la fonte del dato e chi lo compila. Scrivilo insieme all'elenco dei requisiti, non dopo, perché molti errori nascono da campi che esistono in due versioni diverse. Ogni termine usato va definito una sola volta, con lo stesso significato in tutto il documento.

Tipo di informazioneEsempio genericoDove scriverlo
Regola di calcoloUn importo che cambia con la categoria del clienteScenario con tabella delle regole allegata
Dato obbligatorioUn documento non può essere chiuso senza una firmaRequisito funzionale con criterio di verifica
Vincolo normativoConservazione di alcuni documenti per un periodo definitoRequisito non funzionale con riferimento alla fonte
Campo e formatoUn codice che segue una struttura precisaDizionario dei dati con esempi validi e non validi

6. Errori comuni nelle specifiche

Gli errori più frequenti non sono di forma ma di contenuto. Il documento descrive la soluzione invece del problema, oppure presume che tutto sia chiaro perché è chiaro a chi l'ha scritto. Riconoscerli in tempo ti permette di correggere la rotta senza rifare il lavoro, e le voci che seguono sono quelle che compaiono più spesso nei progetti reali. Sono facili da correggere prima dello sviluppo.

Un controllo utile è chiedere a una persona estranea al progetto di riassumere un requisito con parole sue. Se il riassunto cambia significato, la frase va riscritta. Ripeti il test sulle funzioni più critiche, come i pagamenti, le autorizzazioni e la conservazione dei dati, perché lì un'ambiguità costa di più. Il test funziona anche con una persona di un'altra area.

  • Descrivere schermate invece del comportamento che l'utente deve ottenere.
  • Usare aggettivi non verificabili come semplice, veloce o intuitivo.
  • Dimenticare utenti, ruoli e permessi.
  • Non scrivere cosa succede in caso di errore o di dato mancante.
  • Mescolare nello stesso requisito più funzioni diverse.

7. Come verificare che le specifiche siano pronte

Prima di dare il documento allo sviluppo, fai una revisione con più ruoli. Chi usa il processo verifica che il flusso corrisponda al lavoro reale, chi approva controlla le regole e i rischi, chi costruirà il software verifica che i requisiti siano realizzabili e verificabili. Ogni osservazione va chiusa per iscritto, altrimenti resta come ambiguità nel codice. Una revisione di un solo ruolo vede poco.

Un documento è pronto quando ogni requisito ha un identificativo, un criterio di verifica, un responsabile e uno stato. Se manca uno di questi elementi, il requisito non è pronto. Il documento va poi aggiornato come parte del progetto, non archiviato al primo rilascio, perché è lo strumento con cui si valutano tutte le richieste di modifica successive. Scrivi anche la data di approvazione.

8. Come iniziare questa settimana

Scegli una sola funzione, quella che crea più problemi oggi, e scrivine lo scenario principale con le eccezioni più evidenti. Fallo insieme alla persona che la usa ogni giorno, seguendo il lavoro reale e non il processo immaginato. Il risultato sarà una pagina sola, ma già utile per capire come impostare il resto del documento. È già una specifica utile da discutere.

Poi fai leggere la pagina a uno sviluppatore o a un fornitore e chiedi quali domande gli sono venute. Le domande indicano le lacune. Se ti serve aiuto per impostare il perimetro, possiamo guardarlo insieme. Il passo successivo è collegare la specifica al piano di collaudo, che è il vero test di quanto hai scritto. Anche una conversazione basta a capirlo.

Domande frequenti

Il documento di requisiti è obbligatorio?

Non esiste un obbligo generale, ma senza un documento scritto il progetto dipende dalla memoria delle persone. Se il software tocca dati personali o processi regolati, un documento scritto diventa anche una prova di come è stato definito il trattamento.

Chi scrive le specifiche, io o il fornitore?

Il contenuto deve arrivare da te, perché sei tu a conoscere il processo. La forma può essere curata insieme al fornitore, che sa quali informazioni servono per sviluppare. Un fornitore serio ti aiuta a completare il documento e segnala le ambiguità.

Quanto deve essere lungo un documento di requisiti?

La lunghezza dipende dalla complessità del processo, non dal desiderio di sembrare completi. Un documento corto e verificabile vale più di uno lungo e vago. Organizzalo per funzione, così che ogni parte possa essere letta e approvata separatamente, e aggiorna solo le sezioni che cambiano.

Devo descrivere anche l'interfaccia grafica?

Descrivi il comportamento e le informazioni che l'utente deve vedere e inserire, non il disegno dei singoli pulsanti. Un bozzetto può aiutare a chiarire il flusso, ma va trattato come esempio. La grafica definitiva si decide in fase di prototipo, dove puoi verificarla con gli utenti reali.

Come gestisco le modifiche al documento dopo l'approvazione?

Ogni modifica va registrata con data, motivo, autore e impatto su costi e tempi. Il documento approvato resta la base di riferimento, e le variazioni vengono approvate con la stessa procedura della prima stesura. Così puoi sempre sapere cosa era stato concordato e cosa è cambiato.

Nota sul contenuto

Guida informativa di carattere generale. Norme e requisiti tecnici cambiano nel tempo: verifica sempre le fonti ufficiali e valuta il tuo caso specifico con un consulente tecnico o legale qualificato.

CONTATTACI

Parla con il nostro team.

Mostriamo come Altovar si integra nella tua infrastruttura. Nessun impegno, nessun sales pitch. Solo una conversazione tecnica.

PRENOTA UNA DEMO →