Sto creando un Functional Specification Document (FSD) per un progetto. Sono abbastanza confuso su dove dovrei specificare i messaggi di errore? Appartengono alla FSD o fanno parte delle Specifiche tecniche (TSD)?
Ho letto questi articoli per aiutarmi a iniziare a creare FSD:
Questi sono buoni articoli, ma danno solo un'idea generale su cosa debba contenere l'FSD, ma non ci sono articoli su dove mettere i dettagli più specifici.
Gli errori funzionali appartengono al documento delle specifiche funzionali.
Che cosa sono errori funzionali?
Se il prodotto è rivolto all'utente (come un'applicazione desktop o un'applicazione Web), gli errori funzionali sono gli errori mostrati all'utente finale. Ad esempio, quando l'utente invia un file con un tipo MIME errato a un'applicazione Web, appartiene al documento delle specifiche funzionali per spiegare che:
L'applicazione dovrebbe gestire questo caso con garbo (al contrario di un arresto anomalo, che probabilmente non è quello che gli utenti vorrebbero vedere come risposta alla loro azione).
L'applicazione dovrebbe essere in grado di informare l'utente del problema di conseguenza (al contrario di inghiottire silenziosamente l'eccezione e non fare nulla con il file inviato, permettendo all'utente di capire perché la sua azione di presentare il file non ha avuto effetto).
Se il prodotto è un servizio (come un servizio Web o una libreria destinato ad essere utilizzato da altre applicazioni), gli errori funzionali sono le eccezioni propagate al chiamante, ovvero l'interfaccia tra il servizio e il codice che utilizza il servizio.
Se il prodotto è un'applicazione server, gli errori funzionali sono gli errori registrati per aiutare gli amministratori di sistema a capire se l'applicazione ha eseguito l'attività come previsto e per gestire situazioni impreviste. Nota che questo non include i messaggi di debug che sono destinati agli sviluppatori.
Gli errori tecnici appartengono al documento delle specifiche tecniche.
Che cosa sono gli errori tecnici?
Gli errori tecnici sono gli errori che non sono destinati al pubblico principale, descritti nella sezione precedente. Questo include:
Registrazione progettata per gli sviluppatori.
Registrazione progettata per gli amministratori di sistema quando non sono il pubblico principale, cioè quando non sono gli utenti diretti dell'applicazione.
Eccezioni che sono interne al sistema. Queste eccezioni possono attraversare i diversi livelli del sistema, ma di solito non interagiscono con il mondo esterno. In altre parole, come utente (di un'applicazione, di un servizio o di una libreria), non vedrete quelle eccezioni, dato che il sistema sarà in grado di gestirle da sé (eventualmente con la visualizzazione di un errore funzionale).
Casi eccezionali all'interno di un ambito ristretto del sistema. Mentre non è l'obiettivo di un documento di specifiche tecniche elencare ogni eccezione in ogni classe, alcuni casi molto specifici devono essere documentati, spiegando come tale o tale situazione eccezionale viene gestita all'interno del codice.
Tutti i progetti che ho visto in cui a qualcuno importava abbastanza per redigere le specifiche funzionali e tecniche, hanno mancato costantemente alcuni punti.
Pertanto, assicurati di non dimenticare:
La gestione globale delle eccezioni. Il documento delle specifiche funzionali dovrebbe anche spiegare come vengono gestite le eccezioni e gli errori a livello globale, cioè quando non sono gestiti in modo specifico nel codice. Ad esempio, per le applicazioni Web, dovresti spiegare il contenuto di una pagina HTTP 500 (l'utente sarebbe in grado di segnalare un errore? Avrebbe un ID di correlazione se contatterà il supporto?) E il processo dietro di esso: come e dove registrate l'errore? In che modo gli amministratori di sistema saranno informati che l'errore è avvenuto?
Gli errori relativi ai requisiti non funzionali : come gestisci, ad esempio, un carico che va oltre la capacità dell'applicazione web? Un modo è configurare il proxy inverso per mostrare all'utente un messaggio di errore amichevole che spiega cosa è successo. Un altro modo è quello di fare sforzi particolari, sperando per il meglio, e finire con una pagina di errore predefinita del tuo proxy inverso (o un browser) che mostra.
Un altro esempio: come reagirà l'applicazione al disco rigido? Allerta l'amministratore di sistema che sta esaurendo lo spazio? O si arresterebbe semplicemente o si sarebbe comportato in modo strano?
Leggi altre domande sui tag design requirements specifications documentation functional-requirements