Wiley Telling Stories: A Short Path to Writing Better Software Requirements 978-0-470-43700-1 User Manual
Product codes
978-0-470-43700-1
Telling Stories
18
With better support and training, many of the people pressed into service
writing requirements today, regardless of education or background, could do
a better job, and many people who aren’t doing it at all could be taught.
a better job, and many people who aren’t doing it at all could be taught.
If you’re one of those having this work imposed on you and you really think
you’re the wrong person for the job, you should have no shame in making it
known. Tell your boss the firm could save money and free you up to do what
you’re good at if it would hire a technical writer to write requirements.
known. Tell your boss the firm could save money and free you up to do what
you’re good at if it would hire a technical writer to write requirements.
If you can’t get a technical writer or a good business analyst, this book
should be helpful to you as a starting point. If you don’t like to write or think
you are bad at writing, I encourage you to write as little as possible. The most
text‑heavy documents I’ve seen were written by engineers and included many
pages of superfluous material. Follow the guidelines in this book and stick to
short, punchy sections, paragraphs, and sentences. Use lots of diagrams and
if you see more than an inch or two of text anywhere, break it up. Remember,
a comic book is usually a very good story.
you are bad at writing, I encourage you to write as little as possible. The most
text‑heavy documents I’ve seen were written by engineers and included many
pages of superfluous material. Follow the guidelines in this book and stick to
short, punchy sections, paragraphs, and sentences. Use lots of diagrams and
if you see more than an inch or two of text anywhere, break it up. Remember,
a comic book is usually a very good story.
Summary
My advice breaks down to just a few essential points. First there are some very
general ones, some of which we’ve gone into already:
general ones, some of which we’ve gone into already:
Stories are the best way to communicate requirements.
•
We approach writing requirements like you are telling a story.
•
Story elements such as conflict, theme, plot, and character are directly
•
analogous to the requirements process.
Software requirements explain a business problem and the requirements
Software requirements explain a business problem and the requirements
•
of a software solution in nontechnical language.
Software requirements do not include project management details such
Software requirements do not include project management details such
•
as schedule, resources, and cost.
There is no well‑understood distinction between
There is no well‑understood distinction between
•
software requirements
and business requirements.
Structured Analysis defined the basic tools for specifying requirements
Structured Analysis defined the basic tools for specifying requirements
•
in 1979 and has remained an important methodology ever since.
Structured Analysis did not include a narrative structure to hold all of
Structured Analysis did not include a narrative structure to hold all of
•
its parts together.
Combining the basic elements of Structured Analysis with a simple nar‑
Combining the basic elements of Structured Analysis with a simple nar‑
•
rative structure results in a much more effective final document.
Technical writers are best suited to writing requirements, but others can
Technical writers are best suited to writing requirements, but others can
•
adequately do the work with some training and practice.
37001c01.indd 18
1/29/09 10:50:42 PM