I consigli giusti sulla scrittura di documenti di requisiti tecnici

La preparazione di documenti dei requisiti tecnici (conosciuti anche come documenti dei requisiti del prodotto) è una parte tipica di qualsiasi progetto per creare o rivedere un sistema software o altri tipi di prodotti tangibili. Ci sono molti vantaggi per investire tempo e sforzi nella preparazione di un documento sui requisiti tecnici. In questo articolo parleremo di alcuni di questi vantaggi, includendo suggerimenti per scrivere documenti dei requisiti tecnici. Troverai inoltre i consigli e le esperienze di tre esperti: Rachel S. Smith, ex Senior Interface Designer presso il SCU Center for Distributed Learning, Renee Fellman, esperto di risanamento d'impresa pluripremiato e Michael Shrivathsan, vice-presidente dell'area Product Management presso Accompa.

Inoltre, troverai una breve descrizione di altri tipi di documenti dei requisiti che si sovrappongono ai documenti sui requisiti tecnici o vengono confusi con questi. L'articolo contiene anche una discussione su Agile Modeling, un modo per produrre documenti tecnici, e una breve revisione dei requisiti IT per le aziende e gli istituti formativi. 

Sebbene questo articolo costituisca una guida utile per aiutarti a creare un documento tecnico, è anche bene che tu lo faccia "a modo tuo". Ogni azienda segue politiche e pratiche diverse per la documentazione. Assicurati di conoscere le politiche della tua azienda e di sviluppare un documento tecnico che funzioni per te e il tuo team. 

Perché creare un documento sui requisiti tecnici?

 

Rachel S. Smith, author of Writing a Requirements Document, explains that a technical requirement document, “Presents why a product is needed, puts the product in context, and describes what the finished product will be like.” For software projects, a technical requirements document generally refers to how the software will be built including the operating system it is being programmed for and other standards.

 

Secondo Smith, se non si crea un documento sui requisiti tecnici possono insorgere problemi reali. Questi problemi possono includere:

  • Creazione di un prodotto che non risponde a una necessità reale.
  • Sviluppo di "feature creep".
  • Un gruppo all'interno del team che pensa che si stia costruendo una formica, mentre un altro gruppo pensa che si stia costruendo un elefante.

 

Renee Fellman, a Portland, Oregon-based business expert who specializes in turning around businesses on the brink of failure, has found that failure to adequately document technical requirements can cause serious problems for a company that impact their bottom line.

Problems that arise from not having technical requirements documentation can range from simple to complex. “In one company I consulted for,” Fellman said, “Vital FDA compliance issues weren’t being addressed because human resources had failed to do something as simple as assign the duty of taking care of regulatory affairs.”

 

Guida alla gestione dei progetti

Il tuo punto di riferimento per la gestione di tutti i progetti

Un'illustrazione con il logo Smartsheet e le parole Guida 101 alla gestione dei progetti

Vuoi ottenere di più dai tuoi sforzi di gestione dei progetti? Consulta la nostra guida completa alla gestione dei progetti per suggerimenti, best practice e risorse gratuite per gestire il tuo lavoro in modo più efficace.

Visualizza la guida

Il valore dei documenti sui requisiti tecnici

Un documento sui requisiti tecnici consente al tuo team di comprendere reciprocamente cosa è richiesto, tecnicamente, per garantire il successo del progetto o del prodotto. Secondo l'articolo Demistificare le 5 fasi del project management, i documenti sui requisiti tecnici devono essere creati nella fase 2 del ciclo di vita del progetto. Durante questa fase, l'ambito del progetto è già definito e gli obiettivi sono stati determinati. I documenti sui requisiti tecnici offrono inoltre informazioni che ti aiuteranno a:

 

 

Aspettative di preparazione dei documenti sui requisiti tecnici

Chiunque prepari un documento sui requisiti tecnici deve capire cosa comprende un requisito di sistema "buono" e come comunicare queste informazioni in modo chiaro.

  • Tieni presente quanto segue:
  • Sii creativo sulle fonti che scegli di esplorare man mano che analizzi i tuoi requisiti tecnici e utilizza sempre la tua azienda come punto di riferimento di base
  • Aiuta gli altri a comprendere i tuoi risultati utilizzando una lingua facile da comprendere
  • Utilizza i prototipi per capire cosa manca
  • Assicurati di comprendere le interrelazioni, le priorità, i costi, l'implementazione e le conseguenze ambientali quando decidi cosa includere
  • Definisci i limiti del sistema 

Altri tipi di documenti dei requisiti comunemente trovati nelle aziende

Nella determinazione dell'elenco iniziale dei requisiti tecnici, tieni presente che ci sono altri documenti che vengono preparati anche da altri team all'interno della tua azienda. Questi documenti riguardano lo stesso progetto ma sono destinati a pubblici diversi. È molto probabile che alcuni di questi documenti possano contenere informazioni ridondanti. Potresti ritenere che alcuni elementi debbano rientrare nel tuo documento sui requisiti tecnici e non in quello sui requisiti di business o di mercato, ma non preoccuparti: puoi utilizzarli in entrambi. È necessario creare un documento sui requisiti tecnici che funzioni meglio per i tuoi scopi. Assicurati di raccogliere le informazioni più utili per te. 

Michael Shrivathsan, vice-presidente dell'area Product Management presso Accompa, è un esperto sui tipi di documenti sui requisiti e sulle loro funzioni. 

 

“There can be some overlap between business, market, and technical requirement documents,” said Shrivathsan. “Depending on the organization, they may or may not use all these document types. At large companies (1,000 employees plus), they typically do use all three of these docs. Most mid-sized companies (200 employees or more) use at least two of them.” 

Questi report potrebbero contenere informazioni importanti che possono informare, influenzare o creare imprevisti con il documento tecnico. Ecco alcuni altri documenti che possono essere creati da altri reparti per supportare il tuo progetto:

Documenti dei requisiti di business (BRD)
Redazione a cura di: Product Manager, Product Marketing Manager
Pubblico: Business Manager
Revisione e approvazione a cura di: Dirigenti di livello C  

Un documento dei requisiti di business definisce il business case di alto livello e viene solitamente preparato per primo.

Un documento dei requisiti di business definisce l'obiettivo del progetto dal punto di vista dell'azienda. La documentazione per questa fase delinea gli obiettivi aziendali a un livello elevato. I membri di questo team devono essersi incontrati con i business manager appropriati in azienda o presso l'azienda del cliente per raccogliere le informazioni aziendali necessarie relative alle necessità sia della tua azienda che del cliente.
 
Dal documento dei requisiti di business puoi apprendere le seguenti informazioni, che potrebbero aiutarti nel documento dei requisiti tecnici:

  1. La natura delle esigenze dei tuoi clienti
  2. In che modo queste esigenze si allineano alla missione della tua azienda
  3. Come il tuo prodotto, il sistema o il software risolverà le esigenze del cliente a un livello elevato
  4. Un quadro della relazione tra tutte le parti interessate del progetto, attraverso flussi appropriati, organigrammi o diagrammi, consigliato perché garantisce chiarezza

 
Documento dei requisiti di mercato (MRD)
Redazione a cura di: Product Manager, Product Marketing Manager
Pubblico: Business Manager  
Revisione e approvazione a cura di: Direzione 
Un documento dei requisiti di mercato aggiunge ulteriori informazioni al BRD in termini di necessità di mercato, e definisce con precisione il panorama attuale del mercato per prodotti o programmi come quello che stai sviluppando. Sapere qualcosa su ciò che c'è già, su come è commercializzato e a chi, può aiutarti a determinare le lacune in altre funzionalità di prodotto.
 
Dal documento dei requisiti di mercato puoi apprendere le seguenti informazioni, che potrebbero aiutarti nel documento dei requisiti tecnici:

  • Il tipo di prodotto che viene pianificato
  • I clienti target
  • Persone che definiscono:
    • Caratteristiche del cliente
    • Le sfide che devono affrontare
    • Come il prodotto proposto aiuterà a risolvere queste sfide
  • Prodotti concorrenti e i loro vantaggi e svantaggi
  • Modi in cui il tuo prodotto sarà migliore

 
Se nessuno della tua azienda sta preparando i report di cui sopra, potresti dover svolgere del lavoro extra per ottenere il quadro completo dell'universo in cui il tuo prodotto esisterà.

I requisiti tecnici dovrebbero concentrarsi sui risultati desiderati

I requisiti tecnici di sviluppo software includono componenti come la pianificazione dello sviluppo, l'architettura tecnica, i test software e la distribuzione. Fellman consiglia, per una buona documentazione tecnica, di iniziare concentrandosi sui risultati desiderati e non troppo sul processo. Perché? Perché dove vuoi andare determina ogni aspetto del percorso da intraprendere. Ad esempio, non prenderai un cammello per salire in cima all'Everest, ma potresti farlo se il tuo obiettivo finale è raggiungere una tomba antica nel deserto egiziano.
 
Fellman avverte: "Non porsi le domande giuste prima di iniziare a preparare il documento tecnico può portare a un documento che non risolve effettivamente il problema che stai cercando di risolvere." 
 
Le domande, naturalmente, variano a seconda dei tuoi clienti, della tua azienda e del prodotto previsto, ma per i documenti dei requisiti tecnici esplora cosa vuoi che il nuovo sistema o software possa portare a termine, soprattutto dal punto di vista dell'utente. Potresti consultare gli sviluppatori e chiedere, dal loro punto di vista, cosa è fattibile e cosa non lo è.

 

Le checklist dei requisiti tecnici basate su modelli sono strumenti organizzativi preziosi

Usare una checklist per i requisiti, come la checklist con la raccolta dei requisiti di Smartsheet, può aiutarti a concentrarti sui tipi di informazioni da raccogliere come parte dell'analisi dei requisiti tecnici.
  
Assicurati di includere:

  • Requisiti funzionali e attività che eseguiranno
  • Date di riferimento in termini di milestone
  • Requisiti fisici per un prodotto tangibile, come dimensioni, peso, colore, forma, consistenza e robustezza
  • Specifiche dell'ambiente tecnico
  • Dati richiesti
  • Interfacce esterne
  • Compatibilità/portabilità
  • Manutenzione

Raccogli informazioni da diversi gruppi 
Smith suggerisce che le informazioni per questi tipi di documenti possono derivare da una varietà di fonti, tra cui utenti finali, clienti, sviluppatori e altre parti interessate. Le informazioni possono essere raccolte attraverso interviste, sondaggi, questionari, ricerche o anche tavole rotonde tra e all'interno dei team.

Sfrutta l'analisi dell'utilizzo
Identifica i tipi di utenti che utilizzeranno il prodotto e scopri i loro modelli di utilizzo. Ti aiuterà a determinare eventuali requisiti necessari per il livello di prestazioni che desideri ottenere. 

Sviluppa casi d'uso 
I modelli per le interazioni di utenti comuni dovrebbero essere inclusi in un documento dei requisiti tecnici o nel documento dei requisiti di business, utilizzando diagrammi e report dei casi. 

Esplora le esigenze e i risultati desiderati 
Prendi in considerazione la raccolta dei seguenti tipi di informazioni per il documento dei requisiti tecnici:

1. Definisci le aspettative e le esigenze dell'utente finale e come il prodotto verrà utilizzato nel mondo reale. Poniti domande (ecco alcuni esempi):

  • Quale problema principale risolverà il prodotto o software per il pubblico?
  • Cosa desideri che le persone realizzino utilizzando il tuo prodotto o software?
  • In che modo la vita sarà più facile e più produttiva?

2. Definisci la struttura del team e gli imprevisti 

  • Quali membri del team sono responsabili dei diversi aspetti del lavoro? (Ricorda l'esempio di Fellman sopra e assicurati che tutte le responsabilità importanti del lavoro vengano assegnate.)

3. Definisci il prodotto 

  • Usa modellini, narrazioni o elenchi.
  • Definisci chiaramente i requisiti dell'interfaccia.
  • Chiarisci i requisiti del cliente, soprattutto se il prodotto o il software sono stati costruiti in base alle specifiche del cliente.  
  • Definisci le fasi di sviluppo. 
  • Includi passaggi specifici per il completamento e crea un piano iniziale che da adattare man mano che vengono scoperti e decisi ulteriori dettagli.
  • Identifica gli imprevisti esplorando quali parti del processo sono interdipendenti e perché.

4. Crea un prototipo per aiutare a chiarire i risultati che gli utenti prevedono dal nuovo prodotto o del sistema, quando completato


5. Definisci l'intero ciclo di vita di sviluppo del prodotto, comprese le persone, il processo, lo sviluppo software e tecnologico, la gestione dei cambiamenti.


6. Assicurati che ogni requisito del sistema descriva:

  • La funzione pertinente che esegue.
  • Qualsiasi tipo di limiti, in termini di progettazione, legali o vincoli normativi o rischi.
  • Requisiti di progettazione dell'ambiente per l'ubicazione operativa, l'utilizzo o lo stoccaggio.

Considera le qualità del sistema
Considera le seguenti qualità del sistema quando descrivi la qualità del servizio di cui hai bisogno per soddisfare i tuoi requisiti aziendali e quelli degli utenti.

  • Disponibilità - Quanta "operatività" puoi aspettarti che il sistema abbia in base alle risorse, ai servizi e all'accessibilità del sistema da parte degli utenti finali.
  • Capacità latente - In che modo il tuo sistema gestirà picchi imprevisti durante l'uso indipendentemente da un maggior numero di risorse.
  • Prestazioni - Date condizioni specifiche di carico di un intervallo di utilizzi, quale sarà il tempo di risposta e la capacità latente.
  • Scalabilità - Quanto rapidamente è possibile aumentare o diminuire il numero di utenti, senza cambiare l'architettura originale.
  • Facilità di manutenzione - Quanto è facile monitorare, riparare e aggiornare i componenti sia hardware che software? I fattori da considerare includono la pianificazione dei tempi di inattività, le opportunità di manutenzione in base a modelli di utilizzo, tempi critici per la disponibilità dei servizi, piani per la diagnostica e il monitoraggio.
  • Sicurezza - Quanto è sicuro il sistema, comprese le autorizzazioni e l'autenticazione degli utenti e le informazioni durante il trasferimento?

Convalida e affina i tuoi requisiti tecnici

Una volta definiti i tuoi requisiti tecnici, prenditi il tempo necessario per convalidarli e affinarli. Smith afferma: "Abbiamo esaminato fattori come: quante parti interessate hanno richiesto un determinato requisito, quante altre esigenze dipendono da esso, indipendentemente che si tratti di rendere il sistema più facile da utilizzare o di eseguire una funzione che gli utenti non potevano eseguire in alcun modo, nonché altre misure qualitative". 

Per Smith, la convalida dei requisiti è stato un processo per porlo all'attenzione del maggior numero possibile di persone, ascoltare il feedback e discutere le implicazioni legate al mantenere o rigettare un determinato requisito. "Non ci sono scorciatoie. Si tratta di coinvolgere le principali parti interessate e di lavorare con loro per comprendere e risolvere eventuali differenze di opinione." 

Smith avvisa che non saprai mai se hai raccolto tutti i requisiti necessari. "Probabilmente ne raccoglierai più di quanti siano necessari. Ma una volta che li hai raccolti, priorizzali e lavora su quelli più importanti, che rientrano nei tuoi tempi e nel budget. A volte non sono i requisiti più grandi a essere i più importanti."

Mantieni aggiornate le parti interessate  

Oggi esistono strumenti che danno alle parti interessate una visione diretta del processo di sviluppo, in cui possono vedere i progressi tracciati visivamente, rivedere (ma non modificare) i requisiti man mano che vengono implementati e testare i primi prototipi. "Lo sviluppo software è una cosa così difficile", afferma Smith. "Le persone si entusiasmano delle funzionalità prima che vengano sviluppate e possono rimanere molto deluse se le loro aspettative non vengono soddisfatte." Pertanto, mantenere le persone informate e fornire loro aggiornamenti tempestivi e regolari nel modo che preferiscono è fondamentale per la soddisfazione dell'utente finale una volta rilasciato il prodotto. 

Agile Modeling fa per te?

Agile Modeling (AM) è un altro modo per creare e documentare un modello che può essere distribuito nello sviluppo di sistemi e prodotti basati sul software. La sua portata va oltre la documentazione dei requisiti tecnici per includere l'intero processo e combina le best practice in base ai valori e ai principi più efficaci per creare il miglior software possibile, considerati tempi e budget.  

Per saperne di più su Agile Modeling, ecco alcuni libri consigliati:

Modelli di requisiti tecnici vs. Software

I modelli sono facili da utilizzare e il costo è onesto, ma ci sono comunque delle alternative. L'azienda di Shrivathsan, Accompa, realizza un software per la documentazione dei requisiti che gestisce i problemi che potrebbero verificarsi per via di informazioni ridondanti o errate.

Questo software:

  • Traccia le dipendenze tra questi tre tipi di documenti. Se qualcosa nel documento dei requisiti di business cambia, può avere un effetto a cascata sul mercato e sui documenti dei requisiti tecnici. 
  • Fornisce un archivio per conservare tutte le informazioni in modo che possano essere facilmente consultate (Shrivathsan ha detto che in più aziende, queste informazioni possono essere suddivise in più silos, rendendone molto difficile il reperimento e l'uso).

"A parte per i progetti più piccoli, è quasi impossibile tenere traccia di queste dipendenze manualmente", afferma Shrivathsan, "quindi è necessario uno strumento software accessibile."

Consigli per scrivere il documento dei requisiti tecnici

La scrittura di requisiti tecnici è un po' diversa da altri documenti aziendali standard. Ci vuole arte per scriverli in modo che possano essere compresi dalle persone che li utilizzeranno per completare un progetto o costruire un nuovo tipo di software. Ecco alcuni suggerimenti che possono aiutarti a scrivere requisiti tecnici utili:

  1. Utilizza un linguaggio semplice e semplice, in modo che tutti abbiano una comprensione comune di ciò che intendi.
  2. Sii conciso. Inizia con un paragrafo introduttivo, seguito da punti di elenco per migliorare la leggibilità.
  3. Mantieni semplice la struttura delle frasi per trasmettere solo un'idea principale per volta.
  4. A volte un'immagine vale più di 1.000 parole, soprattutto se semplifica un concetto o mostra la relazione tra un concetto e un altro.  

Documenti tecnici per istituti formativi e aziende

Alcuni istituti formativi e aziendali hanno siti Web con pagine dedicate ai requisiti tecnici di base per hardware, software e browser. Se questi requisiti tecnici di base non sono soddisfatti, studenti, facoltà o dipendenti non saranno in grado di accedere alla intranet. Nel caso degli studenti questo significa che non possono prendere lezioni online. Nel caso delle aziende, significa che i dipendenti potrebbero non essere in grado di svolgere il loro lavoro.   

Le informazioni di solito comprendono:

  • Configurazioni minime per le piattaforme Windows e Mac, come la velocità minima del processore o della CPU, la memoria minima e il tipo di sistema operativo.
  • Velocità di connessione di rete per accesso Internet
  • Elenco attuale di browser supportati, oltre a link da cui scaricarli
  • Elenco attuale di plugin supportati, oltre a link da cui scaricarli
  • Informazioni sull'accesso Internet
  • Come registrare un account scolastico o aziendale
  • Software richiesti

I modelli Smartsheet trasformano i tuoi requisiti tecnici in una checklist di lavoro per gestire qualsiasi progetto

Potenzia il rendimento dei tuoi dipendenti con una piattaforma flessibile progettata per soddisfare le esigenze del tuo team e capace di adattarsi alle condizioni mutevoli del lavoro. La piattaforma Smartsheet semplifica la pianificazione, l'acquisizione, la gestione e la creazione di report sul lavoro da qualsiasi luogo, aiutando il tuo team a essere più efficace e ottenere di più. Crea report sulle metriche chiave e ottieni visibilità in tempo reale sul lavoro mentre accade con report di riepilogo, pannelli di controllo e flussi di lavoro automatizzati creati per mantenere il tuo team connesso e informato. Quando i team hanno chiarezza sul lavoro da svolgere, possono ottenere maggiori risultati in meno tempo. Prova Smartsheet gratuitamente, oggi.

 

Collegate persone, processi e strumenti con una piattaforma semplice e facile da usare.

Prova Smartsheet gratis Get a Free Smartsheet Demo