5

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.

Chris Cooper
  • 449
  • 2
  • 4
  • 9
  • Is it is because this is an API and you don't recognize who the users are? – JeffO May 28 '13 at 13:34
  • possible duplicate of [What is the difference between technical specifications and design documents?](http://programmers.stackexchange.com/questions/179554/what-is-the-difference-between-technical-specifications-and-design-documents) and of [how do I write a functional specification quickly and efficiently](http://programmers.stackexchange.com/questions/34356/how-do-i-write-a-functional-specification-quickly-and-efficiently). See also: [What is the difference between requirements and specifications?](http://programmers.stackexchange.com/questions/121289) – gnat May 28 '13 at 13:51
  • 3
    @gnat: And again with the duplicate votes. None of those are duplicates. If the Programmers community really wants these vocabulary questions, they need to accept such questions specifically on their own terms, without conflating other concepts that may (in passing) be similar. – Robert Harvey May 28 '13 at 14:15
  • @JeffO No, who the users are isn't really relevant to me in this case, I'm purely interested in how best to separate the sections of the specification in order to make it a useful document. – Chris Cooper May 28 '13 at 14:27
  • 1
    @ChrisCooper - who the users are may affect how they use your API which is what the functional spec is all about. – JeffO May 28 '13 at 15:08

1 Answers1

19

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:

  1. The system shall indicate when a vehicle is not available, and the reason.
  2. The system shall provide a list of other available vehicles.
  3. The system shall provide a list of possible incentives.
  4. The system shall provide a way to choose a different vehicle.
  5. 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.

Community
  • 1
Robert Harvey
  • 198,589
  • 55
  • 464
  • 673