3

At my job we have a fairly elaborate specifications model. Basically we need to create 3 layers of specifications where each subsequent level elaborates on the previous.

We've got:

  • the top layer which is are the requirements
  • the middle layer which is the functional spec
  • the bottom layer which is the design spec

Usually what goes where is pretty self explanatory. But several times now I've wondered about interface descriptions (file formats, APIs or Databases that are shared with other products/parties) and where they go. Each item in an upper layer must be addressed and elaborated on in each lower layer.

  1. You could argue that since a file format received from a third party is immutable it belongs in the top layer. Our internal "customer" has this file format and wants to do something with it. The downside is that all this detail then needs to be mindlessly replicated through all three layers.
  2. You could argue that it belongs in the bottom layer whether it is a file format you design yourself or one that is imposed on you from the outside. The requirement is only that you "can handle it".

What's the "official" way to do this?

  • 5
    There can be no answer to 'What's the "official" way to do this?', outside of your company, if your company has " a fairly elaborate specifications model". What's your model say you should do? – David Arno Feb 29 '16 at 12:38
  • 2
    First, is your design spec a true design spec? Does it fully define what you are going to be building? Or is it created in parallel with code or after code to reflect what was actually built? – Thomas Owens Feb 29 '16 at 14:13
  • @DavidArno Well, there isn't really an official stance on this internally. Doing these things a rigorously as we do now is still relatively new for us. And there aren't too many folks here who deal with this sort of problem. – Kempeth Feb 29 '16 at 15:31
  • @ThomasOwens, the code is the only true design spec. Anything else is either just wishful thinking in advance, or is supplementary documentation creating from the code. – David Arno Feb 29 '16 at 15:36
  • @DavidArno That is true. However, if your design spec is supposed to be a build-to specification, then it would be suitable to capture interface design there. However, if it's an as-built specification and doesn't exist until well after the code, the your interface designs should be some place else since you should be thinking about your interfaces before your start writing code (although they may not be complete until after). And if your design spec evolves from to-build to as-built, then it is still a good place to capture your interface design. – Thomas Owens Feb 29 '16 at 15:40
5

If you're being rigorous in your interpretation of the three levels, an interface declaration as such would go in the middle level, but it would "extend" into the levels above and below, like this:

Requirement

The ability to export data X into external system Y.

Functional spec

Data export will go through a REST interface with the following endpoints:

...

Design spec

REST interfaces will be implemented via library X, calling services Y...

This would be the same whether you define the interface or you use one that already exists (like a 3rd party file format), except if the interface declaration is already available externally, you will just refer to it in the functional spec, rather than duplicating it.

The above only applies to external interfaces, internal interfaces between different parts of the same system would better be defined in the design spec.

But ultimately what you should think about (as with any documentation) is this: how will this documentation be used? Who is the target audience? Where would I expect a sensible reader to look for the interface specification?


Another way to justify specifying this on the functional level is to think of who you are accountable to if you are about to change something.

  1. If you change something specified in the design spec, that should be the internal matter of your application. Technically no-one else should know about it. If your system passes all the integration tests, you're fine.
  2. If you make a change to something in the functional spec, you'd have to notify all the users of the feature you plan to change, including the external systems connecting to yours.
  3. If you make a change on the requirement level...well, you shouldn't, it's up to the business to set the requirements.
1

This seems pretty subjective. Personally I'd put interface descriptions in the Functional spec (because they are "requirements" rather than "decisions"), or in a separate "appendix" document that doesn't sit on this scale at all. But they'd just as easily fit in the Design spec (because they are implementation details). It's hard to answer this — which, I suppose, is why you've asked it.

The direct answer to your question, though, is that there isn't an "official" way to do it.

  • Functional specs tend to be the what not the how but bleed through from one layer to another does often take place. – Robbie Dee Feb 29 '16 at 12:45
  • @RobbieDee: Exactly. It's subjective as to whether an interface is the what or the how. Generally we put it in the what. What will our application do? It will communicate using this interface. (How will it do so? With software designed thusly: ...) – Lightness Races with Monica Feb 29 '16 at 13:46
  • There can also be some politics at play as to which spec gets updated. If one spec has been signed off but the other is still in a state of flux, then the information is sometimes shoe horned into whatever document is still in progress rather than having to go through what can be an arduous sign off process. – Robbie Dee Feb 29 '16 at 14:15
  • @RobbieDee: Yeah can be – Lightness Races with Monica Feb 29 '16 at 14:15
0

We had a similar documentation system for a large information solutions company I worked for.

The details you've described properly sits in the design spec in my view - if not in a level below this.

To summarise why, this is my take on those spec levels:

Requirements

Defines what is required at a high level. The business rules if you like.

Functional spec

Describes at a high level the parts of the system that will deliver the requirements.

Design spec

Describes the detail (i.e. the "how") - the system internals, the logical DB design, the physical DB design. Anything that requires breaking down further goes into a design document/spec below this.

As you've already outlined, you want to avoid having to push detail up through the documentation layers. If you push the detail into the design spec, this is usually fine but there are of course times where there are is a fundamental change that requires changes across the design. It happens - people forget/misunderstand requirements or chunks gets added and removed.

-1

There are a few ways to handle this, but they tend to not belong in a requirements specification or a design specification. This is especially true if you are building the software internally, but need to release your interface documentation to a broader audience. You probably don't want to release all of your software requirements and internal design information to external entities interested in your interfaces.

At work, we use interface requirements specifications (or interface requirements documents) and interface control specifications (or interface control documents). The interface requirements specifications tend to only exist at a system or subsystem level. By the time you are dealing with a software-only component, the interface requirements have been defined, so we'll just include the pertinent information from the higher level specification (either inclusion or trace - both are easy with a requirements management tool).

The advantage of this is that we tend to not release component specifications (requirements or design) to external parties. Software requirements specifications contain requirements levied by the business to support long-term technology development goals as well as internal customers from systems engineering, SQA, manufacturing, and others. These are requirements that we may not want to expose to external customers for a number of reasons (especially constraints or requirements in support of long-term tech development).

The interface control specification or interface control document simply provides a specification for the inputs and outputs between two or more components, subsystems, or systems. How we write these varies. For some products, a component outputs a standard format so we have an ICD for that format and a separate ICD for the input. We can then go and assemble these pieces in different ways for customers, making a sort of volume of documents all linked together.

Something else to keep in mind, a document doesn't necessarily need to be a Microsoft Word or PDF document. A wiki page or collection of wiki pages (with appropriate edit control and revision history, especially with the ability to export to a static format) is just as much a document as other formats. It's more about the content being available and appropriately linked together in a meaningful manner than the way it's ultimately pulled together.

Interface design and control is a practice from Systems Engineering. NASA has an interesting document about the subject. However, depending on your field, it's probably overkill. You may be able to learn from these practices and tailor them to an appropriate level.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.