From the Editor
IEEE Software, September/October 2000
What’s In a Name?
One consequence of the youthfulness of software engineering is that we have
not standardized our terminology. This might seem like a small matter of
primarily academic interest, but the lack of defined terms has significant
and unexpected consequences. The number of ambiguous terms in software
engineering is practically limitless, and in this column I will focus on
only a few: "requirements," "prototype," "specification," "architecture,"
and "analysis."
Term Limits
Problems with terminology begin as soon as a project gets underway. Suppose
your customer asks you to write a "requirements" document. What do you
write? I have found that different organizations might call any of the
following a "requirements document":
- Half-page software product vision
- Two page list of key features
- 50 page list of detailed end-user-level requirements
- 250 page exhaustive listing of every visual element on every screen,
input-field-by-input-field descriptions of all possible input conditions,
all possible system state changes, detailed description of every persistent
data element, and so on
For my purposes, I have gravitated toward calling Level 1 requirements a
"product vision," Level 2 a "feature list," Level 3 a "functional
requirements document," and Level 4 a "functional specification," but my
usage is by no means standard.
One technique used to pin down requirements is prototyping, which brings on
a second wave of confusing terminology. Some people use "prototype" to refer
to a functioning program that will be evolved into a working program but
which is less robust than the fully functional program will be
("evolutionary prototype"). Other people use it to refer to a non-functional
mock-up that will be used to illustrate how the fully functional system will
look or operate, but which is not, itself, intended to be evolved into the
working system ("throwaway prototype"). Still others use the term
"prototype" to refer to low-quality software that is at an early pre-release
stage of development.
At some point, most project teams create a "specification" or "spec," which
muddies the waters still further. "Specification" seems to refer most
commonly to detailed functional requirements—screen by screen descriptions
of all visual elements, input-field-by-input-field descriptions of all
possible input conditions and system responses, and so on (my level 4
requirements, above). Almost as often, "spec" refers to what I have called
Level 2 or Level 3 requirements. Some people use "spec" to refer to an
architecture document, detailed design, or other work product. One company
used the word "specification" to refer to a document that contained every
piece of information relevant to a project—and the document didn’t have any
requirements information at all.1
"Architecture" has varying meanings, too. Some people use "architecture" to
refer to the design of the user interface, especially to the flow among the
different elements of the user interface that will be visible to the
software’s users, but not to technical implementation work. Others use
"architecture" to mean partitioning a system into subsystems and defining
the interfaces between them. Still others mean anything related to the
functional design of the software—to technical implementation work.
Finally, the meaning of the word "analysis" varies from one organization to
the next. Many use it to refer to an early-requirements activity of
analyzing user needs. Others use it interchangeably with requirements
elicitation and documentation—essentially synonymous with "requirements
engineering." Others use "analysis" to refer to the activities that bridge
requirements gathering to design work. Once again, no meaning is common
enough to allow any single meaning to be declared an obvious standard.
What’s in a Name?
These differences in the ways common software engineering terms are used
can have major consequences. I participated as an expert witness in a
multi-million-dollar lawsuit in which a company sued its former Vice
President of Technology for non-performance of work duties. The company
alleged that it had assigned the VP to develop a prototype and architecture,
and that he had failed to do so. The VP was flabbergasted that the company
could baldly assert that he had not created these work products when in fact
the work products were available for all to see.
It turned out that the VP had developed an evolutionary user interface
prototype and demonstrated it to the company’s senior management. Senior
management was enthusiastic about the prototype and encouraged the VP to
"finish" the prototype. Senior management’s assumption was that the
prototype was a throwaway prototype, and remaining details could be
added quickly as a precursor to the main implementation effort. The VP’s
assumption was the "finishing the prototype" meant evolving the prototype to
a level of robustness and reliability at which it could be released for
commercial use. "Finishing the prototype" meant "finishing the product."
This lead to a critical miscommunication in which senior management thought
the prototyping work could be finished in a matter of days or at most weeks,
while the VP thought the prototype development would take many months,
possibly as long as a year.
At issue in the same lawsuit, senior management had assigned the VP of
Technology to create a "product architecture." The VP’s prototype showed
many details of the user interface design, flow among user interface
elements, and so on. He considered this to be a full-fledged product
architecture. The company’s senior management expected the VP to develop a
functional architecture that defined the software’s decomposition into
subsystems, class hierarchies, network architecture, and so on. As the
company insisted that the VP work harder on the "architecture," the VP spent
more time fleshing out details of the prototype. The more time the VP spent
fleshing out the prototype, the more frustrated the senior management became
that the prototype was taking so much longer than they expected, and the
more frustrated they were that the VP refused to create an architecture.
Coming to Terms
Not every misunderstanding of software engineering terms ends up in court,
but we as a profession face some serious implications of these undefined
terms. The IEEE Computer Society is currently creating a test that will be
used to award "Certified Software Engineering Professional" credentials.
It’s challenging to develop a multiple choice question like "What should go
into a requirements document" (or architecture, prototype, spec, or
analysis) when common usage varies so much.
The legal field has a useful notion called a "term of art." To lawyers, a
term of art is a word that has been analyzed and discussed so much in court
cases and statutes that the word has a precisely defined meaning, a meaning
that may be quite different than the common language meaning. Software
engineering has taken a step in the right direction with IEEE Std 610.12,
"IEEE Standard Glossary of Software Engineering Terminology." I hope that as
the years pass, common usage of these critical terms will gravitate to
specific, precise meanings, and that IEEE Std 610.12 and common usage will
be brought into alignment.
References
1. Thanks for Karl Wiegers for this example.
Standard Vocabulary
The closest we have to a vocabulary standard are the terms defined in
IEEE Std 610.12. Here are the IEEE standard definitions of the terms
used in this column:
Architecture. The organizational structure of a system or
component.
Prototype. A preliminary type, form, or instance of a system
that serves as a model for later stages or for the final, complete
version of the system.
Requirement. (1) A condition or capability needed by a user to
solve a problem or achieve an objective. (2) A condition or
capability that must be met or possessed by a system or system
component to satisfy a contract, standard, specification, or other
formally imposed documents. (3) A documented representation of a
condition or capability as in (1) or (2).
Requirements Analysis. (1) The process of studying user needs
to arrive at a definition of system, hardware, or software
requirements. (2) The process of studying and refining system,
hardware, or software requirements.
Specification. A document that specifies, in a complete,
precise, verifiable manner, the requirements, design, behavior, or
other characteristics of a system or component, and, often, the
procedures for determining whether these provisions have been
satisfied. |
Editor: Steve McConnell, Construx Software, 14715 Bel-Red
Road, #100, Bellevue, WA 98007.
E-mail: stevemcc@construx.com -
WWW:
http://www.construx.com/stevemcc/
