The Critical Nature of Specifications

by Carl Angotti, Managing Director

This paper discusses a fundamental way that specifications and related documentation can assure that a high technology development project can complete in record time.

No Spec, No Project

Often projects “just start,” without going through an initial phase to define what is to be accomplished. What I have observed is that sometimes, this is done with a “bang,”and sometimes with a “whimper.” Managers and team members just “rush off”to begin the “real work,”or they just “wade into the project.”

As can happen, everyone on the team, and the management, assumes that they all collectively know what is to be accomplished without a formal focus on the project deliverables. Later, during design reviews, they discover that they were wrong, and have to repeat portions of the design. Its no wonder that projects can easily drift over time and end up over time and budget.

We have found a good way to remember to write a spec is to add, “No Spec, No Project”to the other old project management adages of “No Money, No Project”and “No People, No Project.”

Keeping High Tech Projects “On Track”

What seems to escape the team is that Specification documents formally define the real world deliverables for the project. They formally describe what the completed design will do, and, just as critically, what it will not be targeted to do at the time the spec is formalized. Anything not specified here, is not a part of the project. Of course, as time goes on, the spec will change. We have found that it is critical to keep track of these changes to keep cost and schedule under control.

What does a Good Specification Contain?

So, if the team doesn't have a good spec outline, what might one contain? In the best scenario the spec describes the important system characteristics and is written down, and signed off by all of the critical team members.

The trick is to have it detailed, but not too detailed. “The trick is to be detailed, but not too detailed.”This is where considerable experience with the systems design within the team is critical. It is most effective if all of the expertise in the team focuses on the Spec Generation, even if it is initially written by one person.

Once that management and a team decide to write a spec, a “generic”spec outline is helpful. A good one might contain some of the following sections:

1. Cover and Signature Page

   This makes the spec stand out from other, less serious, documentation and allows a place for the responsible persons to “Sign Off”that they agree to this set of deliverables. It should contain a date and Revision Number.

2. Summary of Specification Revisions

   This is where any revisions are catalogued by the responsible person and by date. It also includes the purpose of change. This allows the tracking of changes to take place.

3. Miscellaneous Material Used for a Large Specs

   These sections become helpful for larger specifications that run into many pages.

   1. Table of Contents
   2. List of Referenced Documents—Other documents relied upon in the rest of the spec
   3. A very brief description of the Product Definition

4. A General Description of the Function of the System or Program

   This section should contain a clear, short, description of the operation of the code or the system. Ideally it works in conjunction with the Block Diagrams and other support documentation.

5. Definition of Critical System Parameters

   This section can include such items as noise, bandwidth, accuracy, drift, etc for hardware. It can include such items as response time, code size limitations, special algorithms, languages used, etc for software. These often appear in tables or lists.

6. Definition of User Controls and/or User Interface

   This is a description of how the user will interact with the program or system. It needs to be detailed enough to define scope, but need not be extensive. Lots of team judgment is often required here. In complex systems or programs, there may be a separate, more detailed, document to define this important function.

7. Mechanical Characteristics

   This includes Size, Weight, Special Materials, etc. for hardware projects. A similar section for software projects might define specifics of the physical deliverables.

8. Operating and Other Design Environments

   This section is common for hardware projects, but could be useful for software projects that have physical deliverables to the customer.

1. Operating Temperature
2. Storage Temperature
3. Shock and Vibration
4. etc.
9. Tests Used to Define System or Program Operation

   This area defines how the unit will be tested to verify that it meets the specifications. This describes when the “deliverables”are declared completed.

10. Other Tests to Assure the Quality of the Design

    This section can be critical for both hardware and software portions of projects. These tests will normally be performed by groups outside the design group.

    1. Compliance Testing - UL, VDE, FCC, etc
    2. Reliability Analysis and/or Testing
    3. Temperature Testing
    4. Bug checking for Firmware/Software Validation
    5. etc.

How to Obtain a Specification Template

For a more detailed outline of a specification, or help with creating your own, please contact the author at cangotti@360strategicpartners.com, and we can send you some useful templates or discuss your situation with you.

This paper and the material it links to are published with permission of the authors.  All rights to these materials remain with the authors.