!if 0
$Id: //depot/top/anders/html/anders/engphil/specs.sdf#2 $
$Source: /home/anders/public_html/engphil/RCS/specs.sdf,v $
!endif 0

N[align=Center] {{INLINE:<SMALL>[&nbsp;<A HREF="index.html">Back to the Engineering Philosophy Index</A>&nbsp;]</SMALL>}}

!define DOC_NAME        "Levels of Specification"
!define DOC_AUTHOR      "Anders Johnson"
!build_title

{{INLINE:<SMALL>This document is maintained using <A HREF="http://www.cpan.org/authors/id/I/IA/IANC/sdf-2.001.readme">SDF}}{{INLINE:</A>&nbsp. [&nbsp;<A HREF="specs.sdf">View source</A>&nbsp;]</SMALL>}}

H1: Introduction

In order to manage specification changes, it is often useful to categorize
changes semantically.
One way to facilitate this is to eschew the idea of a single monolithic
specification by distinguishing among various "levels" of specification.
This document proposes one possible such taxonomy.

H1: Specification Levels

H2: The Market Requirements Document

The market requirements document (MRD) defines the needs to be addressed
by a product, without necessarily specifying product features in sufficient
detail for a customer to use the product to meet those needs.
It is supposed to reflect what the marketplace is expected to require from
the product I<when it is released>.

Because there is a one-to-one correspondence between MRD's and products,
the MRD might comprise the introduction to the product specification, or
it might be a separate document.

H2: The Product Specification

The product specification defines the properties that a given product is
guaranteed to satisfy.
It is not necessarily public, but is accessible to customers of the
product.
When there is a problem, this specification is used to determine whether
the part is incorrect or is being used incorrectly.

Satisfying the product specification is supposed to guarantee satisfying the
the product's MRD.
Furthermore, it is supposed to be possible to realize every feature defined
by the MRD without relying on product properties not defined by the product
specification.

There may be multiple product specifications that a given design satisfies
(I<i.e.> a given part may be labeled as one of several products).
There may be multiple designs that satisfy a given product specification
(I<i.e.> a distinct but compatible part may be designed).

H2: The Design Specification

The design specification defines the properties that a given design is
required to satisfy.
Satisfying the design specification is supposed to guarantee satisfying the
product specification of each and every product that the design will comprise.

The design specification should differ from the product specification under
any of the following conditions:

^ There are exclusive and/or premium features that are "disabled" through
  obscurity, non-testing and/or the threat of retracting them in the future.

+ There are forward-compatibility features.

+ There are features that might lead to backward compatibility problems later,
  so they are not advertised.

+ Unexposed interfaces must be defined in order to promote reuse of design
  components.

Because the design specification(s) and the corresponding product
specification(s) are closely related, it makes sense to author them as
a single document with conditional text.
However, care must be taken not to deliver the master document to anyone
who is not supposed to have access to all of the slave documents.
(Beware Microsoft WordE<r>'s "Show All Versions.")

H2: The Verification Specification

The verification specification defines the properties that a given design
is required to satisfy in order for it to be I<verifyable> that it satisfies
the design specification.
Satisfying the verification specification is supposed to guarantee satisfying
the design specification.

Whether a given behavior satisfies the product and design specs must
be decidable, but deciding it may be NP-complete or otherwise expensive.
Whether a given behavior satisfies the verification specification must
be decidable in a practical manner.

The design is I<required> to satisfy the verification specification, because
it is otherwise impractical to determine whether it meets the design
specification.
In other words, violating the verification specification constitutes a design
error, even if the design is still alleged to satisfy the design specification.

The verification specification might take the form of an addendum to the
design specification. However, since it is usually much less lenient than
the design specification, it might be able to exist as a stand-alone
document that is significantly more compact.
Ideally, the verification specification takes the form of an executable
program that determines whether a given behavior satisfies the verification
properties, because such a program is generally far more definitive than a
natural language specification.
The existence of such a program also makes design verification much easier.

H2: The Implementation Specification

The implementation specification describes the internal structures and methods
that are used to satisfy the verification specification.

Although the implementation specification is unlikely to be sufficiently
detailed to guarantee satisfying the verification specification, it
greatly facilitates static analysis of the design.
This makes the design process less error-prone, and aids in effective stimulus
design for testing.

Because the implementation plan tends to be volatile, especially near the
beginning of the design process, it is a good idea to guard against
overspecifying the implementation, as this leads to unproductive maintenance
costs.
It makes more sense to make the design as self-documenting as possible, only
using the implementation specification to document that which is important
and not apparent from the design itself.
It also makes sense to document implementation details only after they are
less than 50% likely to change before the design is completed.

H1: General Practices

H2: Tracking

Specifications need to be in writing.
"Folklore" specifications always lead to some combination of difficulty in
obtaining needed up-to-date information, spending too much time
disseminating information, distractions due to unnecessary information,
failures due to unreconciled conflicting assumptions, and general chaos
and confusion.

It is always a good idea to keep specifications under source control, so
that it is possible to determine what changed when and why.
Tracking changes is made significantly easier if it is possible to
enumerate differences between any two versions.
Ideally, specifications are merge-able, such that multiple simultaneous
contributors can be accommodated.

H2: Ambiguity

With the possible exception of the verification specification, each of these
specs are generally written in natural language with diagrams.
This leaves them necessarily open to interpretation,
which is problematic, because they also need to be decidable.
Solving this problem boils down to writing as unambiguously as possible,
which is an art rather than a science.

It is worth mentioning that eschewing ambiguity does not mean abandoning
leniency.
Leniency means that a variety of behaviors are acceptable, whereas ambiguity
means that one cannot decide whether a given behavior is acceptable.
(Without leniency, the design I<is> the specification, which is very bad for
a number of reasons.)

H2: Responsibilities

Because it is generally impractical to formally prove that one specification
satisfies another, there must be a certain amount of overlap in
responsibilities.
For example, the author(s) of the product specification need to review the
design specification, and probably the verification specification as well,
in order to verify that the I<intended> properties of the product are
satisfied.

Determining what ought to be specified is a trade-off between what is desirable
and what is achievable, which is also an art.
One way to do this successfully is for affected parties to engage in
knowledgeable, cooperative negotiation.
For example, the product specification might be negotiated among design,
marketing and the customer(s).
Also, specify exactly what needs to be specified (no more and no less),
and keep all specifications correct and updated (unless and until they become
moot).

H2: Process

We normally like to think of the specification process proceeding sequentially
from high, more lenient, levels to lower, more specific, levels.
Reality is never that simple.
In fact, one can normally expect that the product specification will change
after the design is completed (for example, to de-feature malfunctional
behaviors).
The upshot of this is that it usually makes no sense to have any formal
limitations on which specifications can change when.
Instead, make all changes judiciously, and track them religiously.
(Note that as the specification evolves for follow-on designs, it may be
necessary to branch in order to maintain the specifications of earlier
designs.)

On the other hand, it probably does make sense to gate other activities with
having certain specifications in a coherent state.
For example, it is probably a good policy that all design changes are performed
on an at-risk basis (if at all) until there exists a version of the
verification specification that contains the change and is at least
momentarily acceptable to all affected parties.

N[align=Center] {{INLINE:<SMALL>[&nbsp;<A HREF="index.html">Back to the Engineering Philosophy Index</A>&nbsp;]</SMALL>}}