Datasheet

Telling Stories
15
I can’t tell you the number of times I’ve had to strenuously search through
carefully crafted, richly detailed diagrams and code descriptions trying to
figure out the basic purpose and name of the system under discussion.
My favorite example was a 400‑page functional spec for an equity trading
system that did not say anywhere in the entire document that the system was
for trading equities. I was trying to prove to regulators that the system was
documented, and for lack of about six words (“TraderX is for trading equities”)
the 400 pages were useless as evidence.
Narrative does not have to be rambling, incoherent, and unstructured. It
can be as clear and precise as any diagram, table, equation, or code. It just has
to be done right. Diagrams, tables, equations, and code can be a lot clearer
and more compelling with just a little bit of good old‑fashioned narrative
support. Disparagers of the power of narrative are usually just bad at it, or
they’ve never been taught.
To win over the nonnarrators, I have to broaden their ideas about narrative.
Narrative doesn’t have to be long paragraphs, few headings, and no pictures.
You can tell a story in pictures, text, video, audio, dance, or any other media,
and you can mix and match as you see fit. The key thing is that the media are
effective in getting your point across, and that there is logical, meaningful
structure to the material in which the parts build on each other from begin‑
ning to end.
In creating an effective narrative form for a software requirements docu‑
ment, I use a mix of very specific elements:
Clear, precise words
•
Clear, short sentences
•
Clear, short paragraphs
•
A strong overall structure that breaks up all the content into short sec‑
•
tions with meaningful titles, organized by subject
Lots of diagrams (data flow diagrams, to be specific) showing every
•
process in the system
Structured descriptions of each process
•
Descriptions of all the important data in the system
•
Summary material that ties it all together
•
The result doesn’t look much like what you think of as a story, but if you
pick it up and turn to the first page, you’ll find an actual beginning that states
the problem, proposes a solution, and then compels you to keep reading. You
37001c01.indd 15 1/29/09 10:50:41 PM