I’m writing a specification for a project, and am struggling with separating functional specification from technical specification (see http://www.joelonsoftware.com/articles/fog0000000035.html).
For example, I’m trying to specify the behaviour when a user requests a list of Foo objects they have visibility on. In the functional specification, should I describe what precisely is returned (i.e. the structure of a Foo object) or just that the system returns a list of them and then put the details of the Foo object in the technical specification?
The design is for an API in case that makes any difference. I can’t find many examples of how such an API specification is written.
5
Technical specifications is a broad term. It describes any characteristic of an engineered system that must conform to a specific metric, within some degree of error.
Functional specifications describe the expected behavior of a software system. Program specifications describe what the software is supposed to achieve. This differs from a functional specification in that, while a program specification describes what the system does, the functional specification will describe the manner in which it does it.
I suggest you work for awhile with use cases. At the user level, use cases are the way you describe the behavior of the system, whereas at the code level, the way you describe system behavior is with unit tests. Both techniques can be used to derive functional specifications. As you flesh out the behavior of the system with use cases, it should become clearer what the API should look like.
You begin by creating an informal list of use cases. This document summarizes the process, as does this one. Once you have use cases, you can begin to build functional requirements from them.
Example
When the reserved vehicle is not available due to late returns, the customer is informed of the situation and told about the other vehicle types that are available. The customer is offered an incentive to accept another vehicle type. If the customer is not satisfied, the reservation is cancelled without penalty charges. The customer either accepts another vehicle type or cancels the reservation.
Several functional requirements can be derived from this use case:
- The system shall indicate when a vehicle is not available, and the reason.
- The system shall provide a list of other available vehicles.
- The system shall provide a list of possible incentives.
- The system shall provide a way to choose a different vehicle.
- The system shall provide a way to cancel the reservation.
And so on. From such a list of functional requirements, the elements that need to be present in the API should become readily apparent.