Guida per la scrittura dei requisiti

La scrittura dei requisiti è importante per qualunque progetto.

Importante perché le incomprensioni sui requisiti hanno effetti gravi per i progetti: aumento dei difetti nei prodotti, aumento dei costi, ritardi nei tempi di realizzazione, conflitti da risolvere.

La Guida per la scrittura dei requisiti (“Guide for Writing Requirements” – Copyright (c) 2019 by INCOSE), pubblicata da INCOSE (International Council on Systems Engineering) nel 2019, fornisce indicazioni utili e concrete per la scrittura dei requisiti.

Non è certamente l’unica guida disponibile: sulla scrittura dei requisiti sono stati pubblicati molti libri e centinaia di articoli.

La Guida per la scrittura dei requisiti di Incose ha comunque un paio di punti di forza che la distinguono:

  • È frutto del lavoro ultradecennale del Requirements Working Group di Incose, che comprende aziende ed esperti che operano in settori critici dell’ingegneria dei sistemi e del software
  • È conforme allo standard ISO 29148: 2018 (“Systems and software engineering — Life cycle processes — Requirements engineering”)

La Guida per la scrittura dei requisiti (che ha avuto un aggiornamento minore nel 2022) è acquistabile sul sito di INCOSE: https://www.incose.org

Un’avvertenza doverosa: la lettura della Guida è impegnativa, per lo stile burocratico e con molte ripetizioni. Ciò nonostante, la Guida è ricca di esempi e di indicazioni utili per chi deve scrivere e analizzare i requisiti nei progetti.

Quella che riporto qui è una sintesi degli elementi chiave della Guida, per fornire una chiave di lettura un po’ più semplice dei suoi contenuti e per invogliare ad affrontare il testo completo.


Premessa: Needs e Requirements

La Guida fornisce indicazioni utili per la scrittura di due “cose” simili ma distinte: i Needs (che possiamo tradurre con “necessità”, “bisogni”) e i Requirements (“requisiti”).

I Needs (le Necessità) sono “formal statements of expectations for an entity stated in the language and perspective of stakeholders”. Corrispondono a ciò che viene normalmente chiamato “requisito di business”, o “requisito utente”.

I Requirements (i Requisiti) sono il frutto della trasformazione dei Needs (Necessità) che avviene nel processo di requirements analysis.


GUIDA PER LA STESURA DI REQUISITI DI INCOSE – SINTESI

CARATTERISTICHE DELLE FORMULAZIONI DI NECESSITÀ [cioè i requisiti espressi dagli stakeholder] E REQUISITI [cioè i requisiti precisati dagli analisti].

Si riferiscono a come deve essere scritto il singolo requisito (o la singola necessità).

C1 – NECESSARIA

La formulazione di necessità o requisito definisce una capacità, caratteristica, vincolo o fattore di qualità essenziale, necessario per soddisfare un concetto, una necessità o un requisito principale. Se non viene inclusa nell’insieme di necessità e requisiti, si verificherà una mancanza che non può essere soddisfatta implementando le altre necessità o gli altri requisiti formulati.

C2 – APPROPRIATA

L’intento specifico e il livello di dettaglio della formulazione di necessità o requisito sono appropriati per il livello [di astrazione] dell’entità a cui si riferisce.

C3 – NON AMBIGUA

Le formulazioni di necessità devono essere scritte in modo che l’intento degli stakeholder sia chiaro. Le formulazioni di requisiti devono essere formulate in modo che il requisito possa essere interpretato in un solo modo da tutti i lettori previsti.

C4 – COMPLETA (solo per i requisiti)

La formulazione di requisito descrive in modo sufficiente la capacità, caratteristica, vincolo o fattore di qualità necessario per soddisfare la necessità, senza il bisogno di altre informazioni per comprendere il requisito.

C5 – SINGOLARE

La formulazione di necessità o requisito dovrebbe indicare una singola capacità, caratteristica, vincolo o fattore di qualità.

C6 – REALIZZABILE

La necessità o il requisito possono essere realizzati entro i vincoli esistenti (ad esempio: costo, pianificazione, tecnico, legale, etico, sicurezza) con un rischio accettabile.

C7 – VERIFICABILE (solo per i requisiti)

Il requisito è strutturato e formulato in modo che la sua realizzazione possa essere dimostrata (verificata) in termini di soddisfazione del cliente al livello in cui il requisito esiste.

C8 – CORRETTA

La necessità deve essere una rappresentazione accurata del concetto da cui è stata derivata. Un requisito deve essere una rappresentazione accurata della necessità da cui è stato derivato.

C9 – CONFORME

Le singole necessità e requisiti dovrebbero conformarsi a un modello di stile approvato o ad uno standard per la stesura e la gestione di necessità e requisiti.


CARATTERISTICHE DEGLI INSIEMI DI NECESSITÀ E REQUISITI

Si riferiscono a come deve essere costituito un documento di specifica (in qualunque formato) che comprende un insieme di requisiti (o di necessità).

C10 – COMPLETO

L’insieme di necessità o requisiti per un determinato sistema è autonomo e sufficiente per descrivere in modo adeguato le capacità necessarie, le caratteristiche, i vincoli, le interfacce, gli standard, le normative e/o i fattori di qualità necessari per soddisfare le necessità, senza richiedere altri insiemi di necessità o requisiti al medesimo livello di astrazione.

C11 – COERENTE

L’insieme di necessità contiene singole necessità che sono uniche, non confliggono o si sovrappongono con le altre necessità contenute nell’insieme, e le unità e i sistemi di misura che utilizzano sono omogenei. Il linguaggio utilizzato all’interno dell’insieme di necessità è coerente (cioè, le stesse parole vengono utilizzate in tutto l’insieme per significare la stessa cosa).

L’insieme di requisiti contiene singoli requisiti che sono unici, non confliggono o si sovrappongono con gli altri requisiti contenuti nell’insieme, e le unità e i sistemi di misura che utilizzano sono omogenei. Il linguaggio utilizzato all’interno dell’insieme di requisiti è coerente (cioè, le stesse parole vengono utilizzate in tutto l’insieme per significare la stessa cosa).

C12 – REALIZZABILE

Gli insiemi di necessità e requisiti possono essere realizzati entro i vincoli esistenti (ad esempio, costo, pianificazione, tecnico) con un rischio accettabile.

C13 – COMPRENSIBILE

Le formulazioni di necessità e dei requisiti devono essere scritte in modo tale da essere chiari su ciò che ci si aspetta dall’elemento interessato e sulla sua relazione con il sistema di cui fa parte.

C14 – VALIDABILE

Deve essere dimostrato che l’insieme delle necessità porterà al raggiungimento degli obiettivi e degli scopi del prodotto, delle aspettative degli stakeholder, dei rischi e dei concetti entro i vincoli (come costo, pianificazione, aspetti tecnici, conformità legale e regolamentare) con un rischio accettabile.

Deve essere dimostrato che l’insieme di requisiti porterà al raggiungimento delle necessità e dei requisiti di livello superiore entro i vincoli (come costo, pianificazione, aspetti tecnici e conformità regolamentare) con un rischio accettabile.


REGOLE PER LE FORMULAZIONI DI NECESSITÀ E REQUISITI E DEGLI INSIEMI DI NECESSITÀ E REQUISITI

*** PRECISIONE

R1 – Struttura della frase

Usare una frase strutturata.

R2 – Utilizzare la forma attiva

Usare la forma attiva nella frase principale della necessità o del requisito, con l’elemento responsabile chiaramente identificato come soggetto della frase.

R3 – Soggetto Verbo

Assicurarsi che il soggetto e il verbo della frase della necessità o del requisito siano appropriati per il livello a cui la necessità o il requisito si riferisce.

R4 – Utilizzare termini definiti

Definire tutti i termini rilevanti.

R5 – Utilizzare articoli determinativi

Usare l’articolo determinativo “il” invece dell’articolo indefinito “un”.

R6 – Unità di misura

Usare le unità di misura appropriate quando si indicano le quantità.

R7 – Evitare termini vaghi

Evitare l’uso di termini vaghi.

R8 – Nessuna clausola generica

Evitare clausole generiche, espressioni come “per quanto possibile”, “il meno possibile”, “se possibile”, “il più possibile”, “se dovesse risultare necessario”, “se necessario”, “nella misura necessaria”, “come appropriato”, “come richiesto”, “nella misura del possibile”, “se praticabile” e “se possibile”.

R9 – Nessuna clausola aperta

Evitare clausole aperte, espressioni come “tra cui, ma non solo”, “ecc.” e “così via”.

*** CONCISIONE

R10 – Infiniti superflui

Evitare gli infiniti superflui, come ad esempio “Il sistema deve essere progettato per essere in grado di…” anziché semplicemente “Il sistema deve…”

R11 – Clausole separate

Usare una clausola separata per ciascuna condizione o qualifica da specificare.

*** NON AMBIGUITÀ

R12 – Grammatica corretta

Usare la grammatica corretta.

R13 – Ortografia corretta

Usare l’ortografia corretta.

R14 – Punteggiatura corretta

Usare la punteggiatura corretta.

R15 – Condizioni Logiche

Usare una convenzione definita per esprimere espressioni logiche (come AND, OR, NOT).

R16 – Evitare il negativo

Evitare l’uso di espressioni al negativo.

R17 – Evitare simbolo obliquo

Evitare l’uso del simbolo obliquo (“/”), come ad esempio nell’espressione “e/o”.

*** SINGOLARITÀ

R18 – Scrivere frasi singole

Scrivere una singola frase che contenga un singolo pensiero qualificato da clausole subordinate rilevanti.

R19 – Evitare combinatorie

Evitare espressioni combinatorie come “e”, “o”, “poi”, “a meno che”, “ma”, “così come”, “ma anche”, “tuttavia”, “se”, “nel frattempo”, “mentre”, “invece” e “in caso contrario”.

R20 – Evitare scopi

Evitare frasi che indicano lo scopo per cui la necessità o il requisito è stato formulato.

R21 – Evitare parentesi

Evitare parentesi e parentesi quadre contenenti testo subordinato.

R22 – Enumerazione

Enumerare gli elementi di un insieme in modo esplicito, invece di utilizzare un unico raggruppamento per denominare l’insieme.

R23 – Contesto

Quando una necessità o un requisito è correlato a un comportamento complesso, fare riferimento a un diagramma o a un modello di supporto.

*** COMPLETEZZA

R24 – Evitare pronomi

Evitare l’uso di pronomi e pronomi indefiniti, ripetere i sostantivi per intero.

R25 – Uso di intestazioni

Evitare l’uso delle intestazioni per spiegare o far comprendere il requisito.

*** REALISMO

R26 – Evitare assoluti

Evitare l’uso di assoluti irrealizzabili, come “disponibilità al 100%”.

*** CONDIZIONI

R27 – Condizioni esplicite

Indicare esplicitamente le condizioni di applicabilità del requisito.

R28 – Liste esplicite di condizioni per azione

Esprimere le condizioni in modo esplicito per ogni singola azione, invece di fornire elenchi di azioni per una condizione specifica.

*** UNICITÀ

R29 – Classificare

Classificare la necessità o il requisito in base agli aspetti del problema o del sistema a cui si riferisce.

R30 – Esprimere una sola volta

Esprimere ogni necessità e requisito una e una sola volta.

*** ASTRAZIONE

R31 – Evitare soluzioni

Evitare di indicare una soluzione di design, a meno che non ci sia una giustificazione per vincolare il design stesso.

*** QUANTIFICATORI

R32 – Quantificatori universali

Usare “ogni” invece di “tutti”, “qualsiasi”, o “entrambi” quando è prevista la quantificazione universale.

*** TOLLERANZA

R33 – Intervallo di valori

Definire le quantità con un range di valori appropriato per il livello indicato.

*** QUANTIFICAZIONE

R34 – Misurabile

Fornire obiettivi di prestazione specifici e misurabili, appropriati al livello in cui è formulata la necessità o il requisito.

R35 – Indefiniti temporali

Definire le dipendenze temporali in modo esplicito anziché utilizzare termini temporali indefiniti, come “eventualmente”, “fino a quando”, “prima”, “quando”, “dopo”, “come”, “una volta”, “più presto”, “più tardi”, “istantaneo”, “simultaneo”, “mentre” e “alla fine”.

*** UNIFORMITÀ DEL LINGUAGGIO

R36 – Utilizzare termini coerenti

Usare ciascun termine e unità di misura in modo coerente in tutti gli insiemi di necessità e requisiti.

R37 – Definire acronimi

Se vengono utilizzati acronimi nelle formulazioni di necessità e requisiti, utilizzare un insieme coerente di acronimi.

R38 – Evitare abbreviazioni

Evitare l’uso di abbreviazioni nelle formulazioni di necessità e requisiti.

R39 – Guida Stile

Utilizzare una guida di stile a livello di progetto per le singole formulazioni di necessità e requisiti.

*** MODULARITÀ

R40 – Requisiti correlati

Raggruppare insieme i requisiti correlati tra loro.


R41 – Strutturazione

Conformarsi a una struttura definita o a una template per gli insiemi di necessità e requisiti.


Altri materiali sulla gestione dei requisiti

Formazione

Corso: Gestione dei requisiti e specifica dei documenti di analisi