Writing Technical Specifications in the Present

Technical specifications are improved in several ways with one easy procedure - writing them in the present tense. That is, rather than trying to specify constraints on a product that does not yet exist, describe the product as though it already existed.

That's a big change for most people. Most people write technical specifications in the future tense; "the sensitivity shall be -113dBm". In this article we will see how this simple change can produce specifications that are

easier to write
easier to maintain
remain useful longer

The Spec is Easier to Write

When a specification is written in the future tense, the language tends to become unclear and somewhat convoluted. Words like "will", "shall" and "should" have to be used, and often these are made to take on special meanings with respect to whether parameters are mandatory or not. Conversely, when the specification is written in the present tense, the language is clear and unambiguous.

Furthermore, the use of words like "will" tends to lead to thinking and writing about what will be done, i.e. how the design is to be implemented. It is easy to find oneself writing things like "an iterative development method will be used". Constraints on how the specification is to be achieved do not belong in a technical specification. With a specification written in the present tense, describing the product as though it already existed, it is much easier to focus on describing what the product is, rather than how this is to be achieved.

The Spec is Easier to Maintain

A conventional specification, written in the future tense, reflects the goals at the start of the design phase. As the design evolves you are likely to want to make changes. During the design, engineering trade-offs will be made between different parameters; specifications that turn out to be too difficult or expensive to meet may be relaxed; and it may be discovered that in some areas performance much better than called for can be achieved. Typically these ongoing changes to the specification will be negotiated between the design team and the project manager, and documented in the minutes of regular review meetings.

Because a conventionally-written specification is a forward-looking document, the tendency is to see it as a historical record of the goals at the start of the design phase. Once the design has started, it is awkward to change the specification to reflect ongoing progress whilst still writing in the future tense.

With a specification written in the present tense, however, the specification is simply a description of the product. As the design evolves it is natural to update this description with the agreed changes. Thus, rather than being documented separately in meeting minutes or specification errata (or worse, not formally documented at all), the changes are incorporated in the specification, which remains at all times an accurate description of the product.

The Spec Remains Useful

When you have finished the design and development of your product, you will find that your technical manual (or service manual) is already written. The specification, which you have kept up-to-date during the development process, is now automatically a complete technical description of the product. You may need to tidy-up some details, but the bulk of the work will already be done.

With a conventional specification you would have two problems; it would likely not have been kept up-to-date and would still reflect the goals at the start of the project rather than what you ended up with, and it would be in the wrong tense, with every single sentence needing to be re-written.

Conclusions

This simple change to the way you write technical specifications takes a bit of getting used to, but will deliver benefits throughout the design process.

Keep it Technical

Keep the Technical Specification simple, maintainable and relevant by putting non-technical requirements in a Statement of Work.

There is a great temptation to include non-technical or contractual information in a technical specification. For the same reasons that using the present tense leads to a much clearer, easy to maintain and usable specification - so does keeping out any non-technical aspects.

Consider something as simple as the target works-cost-price. This may be considered a technical parameter - but is it really? If it is included in the technical specification then would you be happy giving that specification to a potential customer (who could then calculate your profit margin)?

By separating commercial and contractual details such as market information, costs, timescales, deliverables and development constraints into a separate document, you ensure that the technical specification can be seen by those who need it without concern about commercial secrets. This second document is often known as the Statement of Work.

About the Author

Matthew Kendall is a principal of Ionocom Communications Inc., Vancouver, BC.

He has worked in electronic product design since 1987, first in Reading, England, and lately in Vancouver, BC, Canada.

He can be reached by email at matthew@ionocom.com.