Datasheet

Telling Stories
9
to be the point person to deal with IT. One of the senior managers thinks it
would be a good idea to write what she calls a “business requirements docu‑
ment.” Or perhaps IT has appointed you, the harried software development
manager, to write what they call a “software requirements document.”
Why Have We Turned from the Path of Righteousness?
So if writing a requirements document is such an obvious and important thing
to do, and the consequences of not doing it are so severe, why is it often not
done, or done very badly? This topic leads to an early digression. Knowing
the answer to this question is not critical to learning how to write better
requirements documents, but I have so often had to defend and justify the
very necessity of the effort that I’m certain many of you will, too. It’s helpful
to understand how things got to be the way they are now and also to be ready
to answer common protests about the process.
Let’s begin with a brief history of writing software requirements. In the
middle of the twentieth century, in the early days of the computer age, it was
very expensive and time consuming to develop software. There weren’t many
engineers and there were few tools to automate their work. The wisest of
the mid‑century software makers, probably after some missteps, realized the
need for writing clear and precise requirements before doing much develop‑
ment work. One of the best, Tom DeMarco, wrote a book named Structured
Analysis and System Specification
2
that elegantly defined a standard for explain‑
ing software systems and writing requirements that came to be known simply
as Structured Analysis. Structured Analysis explains systems as a series of
processes that are represented in “Data Flow Diagrams.” Mini‑specs written
in “Structured English” explain all of the process, and the “Data Dictionary”
and “Data Structure Diagrams” describe and represent all of the system’s data.
There is more to it, of course, but these are the most important and basic ele‑
ments. Structured Analysis was the primary way to do this work for most of the
twentieth century, and in many ways it still is, especially in large organizations
like corporations, government, and the military. Most of the ideas in this book
are in some way part of Structured Analysis. The standard I recommend for
data flow diagrams comes directly from Structured Analysis and is often called
the Yourdon DeMarco data flow diagram. (Tom Demarco often partnered with
Edward Yourdon, another giant in systems analysis.) An example follows.
2
DeMarco, Tom. Structured Analysis and System Specification. Yourdon Press Series
37001c01.indd 9 1/29/09 10:50:41 PM