usage: detail(ed) design

[Richard Dimock <red -at- ELSEGUNDOCA -dot- ATTGIS -dot- COM>]

Dee asked whether to use "detailed design" or "detail design".


In this corner of AT&T, which does large computer systems,
we use "detailed design" specifications to document the nitty gritty
of a software design.

The usual sequence here is for a software architect to ding up
the broad requirements, making sure the new software would meet
the needs and also fit in with other broadly associated software
and hardware of the total system.

Following that, the software is blocked out into more specific
modules, and programmers begin planning how to do their coordination
among modules.

The detailed design comes in designing the guts of each module.
This is what gets documented in a detailed design spec. The spec is
for internal use only.

We writers of external manuals use the detailed design spec to better
understand the software operation. We also have "Feature Usage
Specifications" for human interface information.

Some programmers improperly use the "detail" word verbally, but
never in written communications. As Webster's would say, the use
of "Detail" is deprecated.

It is NOT, repeat NOT the design of one or more "details" that
the programmer is doing, because the overall module design is still
taking shape. A "detail" would be the preloading of a counter or
a check of a boundary condition.

The programmer is doing a "detailed" design which covers the larger
scopes of organization, coordination, self-checking, etc. The
programmer is adding the details as needed in his sequence, but is
not totally concentrated on details alone.


Give THAT to your disagreeable authors. Mark my words, no Senior
Analyst Architectural Consulting Software Chief Engineer wants to
be branded with the label "detail person". The status is in the
broader scopes. You are trying to protect their professional
appearance by using "Detailed Design" which implies a broader
scope of abilities compared to the pedestrian design of petty
details.

If you present it smoothly, they will love you for it!

Dick Dimock     Artfully Senior Tech Writer of El Segundo
AT&T Global Information Solutions
El Segundo, CA
                ** Eat Crow Episode 10 **
                The farmer offered his hand for a shake,
                grounding the rifle butt. The rebel
                shook his hand warmly.

                "I'm Johnny Yuma, the Rebel."
                "I'm Fudd, Farmer Fudd, Call me Farm."
                Soon they were chatting about families
                and homes and the state of the armed
                insurrection thereabouts.