Where should I specify validation messages?

Question

I'm creating a Functional Specification Document (FSD) for a project. I'm pretty confused as to where I should specify error messages? Do they belong in the FSD, or are they part of the Technical Specification (TSD)?

I've read these articles to help me get started with making FSDs:

1. How to Write a Good Functional Specification
2. Painless Functional Specifications

These are good articles, but they only give general idea about what FSD should contain, but no articles about where to put the more specific details in.

Answer 1

Functional errors belong to the functional specification document.

What are functional errors?

• If the product is user-facing (such as a desktop application or a web application), then functional errors are the errors which are shown to the end user. For example, when the user submits a file with a wrong MIME type to a web application, it belongs to the functional specification document to explain that:

  1. The application should handle this case gracefully (as opposed to a crash, which is probably not what your users would like to see as a response to their action).

  2. The application should be able to inform the user about the problem accordingly (as opposed to silently swallow the exception and do nothing with the submitted file, letting the user to figure out why his action of submitting the file had no effect).

• If the product is a service (such as a web service or a library intended to be used by other applications), then functional errors are the exceptions which are propagated to the caller, i.e. traverse the interface between the service and the code which uses the service.

• If the product is a server application, then functional errors are the errors which are logged in order to help system administrators figure out whether the application performed its task as expected and to handle unexpected situations. Note that this does not include debugging messages which are intended for developers.

Technical errors belong to the technical specification document.

What are technical errors?

Technical errors are the errors which are not intended to the primary audience, described in the section above. This includes:

• Logging intended for developers.

• Logging intended for system administrators when they are not the primary audience, i.e. when they are not the direct users of the application.

• Exceptions which are internal to the system. Those exceptions may traverse the different layers of the system, but usually will not interact with the outside world. In other words, as a user (of an application, a service or a library), you won't see those exceptions, as the system will be able to handle them itself (eventually resulting in a functional error being shown).

• Exceptional cases within a narrow scope of the system. While it is not the goal of a technical specification document to list every exception in every class, some very specific cases need to be documented, explaining how such or such exceptional situation is handled within the code.

---

All of the projects I've seen where somebody cared enough to draft functional and technical specifications consistently missed a few points.

Therefore, make sure you don't forget:

• The global exception handling. The functional specification document should also explain how the exceptions and errors are handled on global level, i.e. when they are not handled specifically in code. For instance, for web applications, you should explain the contents of a HTTP 500 page (would the user be able to report a error? Would he get a correlation ID if he will contact the support?) and the process behind it: how and where do you log the error? How the system administrators will be informed that the error happened?

• The errors related to the non-functional requirements: how do you handle, for instance, a load which is beyond the capacity of the web application? One way is to configure the reverse proxy to show to the user a friendly error message explaining what happened. Another way is to make to particular efforts, hoping for the best, and ending up with a default error page of your reverse proxy (or a browser) showing up.

  Another example: how would the application react to the hard disk filling up? Would it alert the system administrator that it's running out of space? Or would it simply crash, or start behaving strangely?