|Practical Software Requirements
A Manual of Content and Style
Benjamin L. Kovitz
1998 | 448 pages | B&W
|Out of Print|
Practical Software Requirements is a comprehensive guidebook for the programmer or manager writing requirements for the first time, as well as the experienced system analyst.
The author takes a unique approach to the subject: that a useful requirements document derives from the techniques employed by programmers and interface designers. His in-depth treatment includes non-hierarchical ways to break down complex problems, elements of the problem domain, and different information needed for different problem types.
An extensive section on style covers the nuts and bolts of making the information understandable: how to group and sequence topics, how to word a definition, even how to avoid boring the reader.
This unusual, example-filled book covers all aspects of a daunting but critical task: giving development staff all the information they need to do their jobs.
- Elements of a software problem
- User (and other) interface design documentation
- How useful requirements derive from known programming techniques
- Describing the problem domain
- Non-hierarchical methods for breaking down problems
- Applying Michael Jackson's "problem frames"
- Common mistakes and how to fix them
- Example documents from real projects
The book's Author Online Forum is open to everyone; you don't need to own a copy of the book to join.
ABOUT THE AUTHOR
Ben Kovitz, a freelance consultant, has 15 years of experience in software engineering, both reading and writing requirements. He has worked as programmer, tester, system analyst, user-interface designer, and technical writer.
Two sample chapters are available for download.
This book is about how to write two kinds of documents needed in the early stages of many software development projects: a requirements document, which describes desired effects to be produced by the software, and a program specification, or interface design, which describes the outward behavior of the computer that produces those effects--the behavior of input/output devices.
Together, these documents provide the information that programmers need to create a program that causes the behavior described in the specification and ultimately fulfills the requirements. The same information provides the baseline against which a tester can design test plans, as well as the operating procedures and background information that a technical writer can put into a user's manual or on-line help.
Many people have a need to write these documents:
- System analysts--the people who serve as the liaison between the customer and the rest of the development team. In larger organizations, writing requirements is traditionally the responsibility of a system analyst. This book provides system analysts with many writing techniques to make their documents clearer and more useful to the people who read them, as well as a clearer delimitation of requirements from other aspects of the software than that found in most books.
- User-interface designers--the people who draw the screens and invent the conceptual world in terms of which an end user is to think when operating the software. For user-interface designers, this book explains the information that programmers, testers, and technical writers need from a user-interface design document to do their jobs, and how to present it tersely and crisply.
- Programmers--particularly those in small companies that are in the process of adding more rigor to their development processes. Many of these companies don't have system analysts and are now recruiting their programmers to write requirements documents for the first time. Indeed, many programmers already do a great deal of requirements engineering and interface design without calling them by those names. For many programmers, defining the problem and choosing the interface behavior to solve that problem is the part of their job that they find most fascinating; many consider these jobs the most essential part of programming. This book construes the word programming more narrowly, to allow careful focus on requirements and interface design as distinct tasks.
- Project managers called upon to write requirements. Especially in small shops, people work in many roles. Often a project manager has the most contact with a customer and is, therefore, the most logical choice to write the requirements document. This can be a daunting task, especially the first time, and especially if no one else in the company has experience writing requirements. This book provides many concrete examples and both high-level and detailed guidance to help a newcomer get started.
Part I, Groundwork, presents the underlying principles that distinguish requirements, interface design, and program design. These principles draw heavily on the landmark work of Michael Jackson, presented in more theoretical form in his book, Software Requirements & Specifications: A Lexicon of Practice, Principles and Prejudices.
Chapters 1 and 2 cover background about how programmers really write programs and how requirements must be tailored to be useful to them. Chapter 2 defines the concept of a software problem. Chapter 3 relates software problems to the principal elements of their solutions, creating the foundation upon which the rest of the book is built.
Chapters 4 through 6 present Jackson's concept of a problem frame: a way of casting the principal elements of a software problem into a form suitable for detailed documentation and for solution by known (or unknown) techniques. Chapter 4 introduces the fundamental elements of domains, shared phenomena, and requirements. Chapter 5 describes five commonly recurring types of software problems and how to frame them. Chapter 6 gives examples of how to apply problem frames to the task of breaking down large, complex problems into simple ones. The technique, unlike most, does not work by hierarchical decomposition. Instead, it works more flexibly, allowing any kind of overlap between the elements of one subproblem and the elements of another.
Part II, Content, gives detailed information about the content to include in each type of document, along with tips on how to describe that content simply and clearly.
Chapter 7 describes the jobs of each person on the development team who reads requirements or specifications, and the information they need. Chapter 8 is a set of two content checklists, one for each type of document. The checklists are flexible guidelines to help you spot needed information that you might overlook, and are not generic tables of contents to force onto any document. Software problems and their solutions are far too varied for that.
Chapter 9 explains how to document two kinds of sets that appear in the vast majority of software problems: classes and relations between classes. The principal technique shown is the standard entity-relation diagram, or class diagram, supplemented by guidance on how to describe, in text, all of the information sketched in the diagram. Chapter 9 also shows how to describe queries that a piece of software is to answer.
Chapter 10 is about techniques for describing sequences and, in particular, sequences of events. This includes description techniques for events themselves, which are needed in a requirements document, and for the computer's and users' responses to these events, which are needed in the program specification.
Chapter 11 attacks the particularly tough problem of how to describe causal relations and rules. These causal relations can exist among the phenomena in the world that the software interacts with, in which case they are described in a requirements document, or they can be the causal rules according to which the computer behaves, in which case they are described in a program specification. As in chapter 10, a variety of techniques are presented for the reader to adapt to the peculiarities of a particular problem.
Chapter 12 addresses a number of miscellaneous topics related to content, including elicitation, the temptation to force the concepts of object-oriented design onto problem-domain description, and the hazards of use cases.
Part III, Style, is about how to choose among the many forms with which to present the same content. Much of this information is standard elements of good technical writing, though focused exclusively on requirements and specifications.
Chapter 15 presents a number of broad principles of technical writing, followed by a list of common mistakes in requirements documents with advice on how to correct them. Most of these mistakes grow out of a too-rigid set of concepts or procedures for writing requirements--forcing the content to fit the descriptions rather than the other way around.
Chapter 14 presents techniques of organization: how to group information together and how to choose the sequence in which to present that information. The strategy is always to build a table of contents from the content identified in Part II, and not to start with a table of contents and fill it in without regard to the specifics of the project.
Chapter 15 is a haphazard collection of guidance on small details: guidance on laying out the page to be most readable, how to reword vague sentences, information to put on the title page, how to word a definition, and so on.
Part IV, Examples, contains two example documents from a real project.
Chapter 16 is the requirements document for a small piece of software to track bugs discovered during software development at Information + Graphics Systems, Inc., in Boulder, Colorado.
Chapter 17 is a set of excerpts from the user-interface design document for the same project. These excerpts contain many examples of information that is very tricky to document simply.
WHAT REVIEWERS ARE SAYING
P. Abrahams writes "In a field that has been driven by rigid methodologies, it is a pleasure to read a book that takes a practical, undogmatic approach to developing the requirements for a software system...The book is well organized, literate, and readable...a delightful discovery."
--ACM Computing Reviews, May 1999
"In short, Kovitz has written a fresh, lively, honest, funny, and provocative book on a serious engineering topic -- not an easy thing to do...Kovitz views requirements as communications between humans, and rightly stresses the value of clear, readable documents...Kovitz' book will quickly become essential background (and possibly foreground) reading for would-be and practising systems engineers."
--Ian Alexander's Reviews of Books on Requirements Engineering
Ben Kovitz' book, Practical Software Requirements: A Manual of Content and Style, has received several notable reviews and endorsements recently. One is a thorough and lengthy piece written by Alan Zeichick in the August 1999 issue of Software Development Magazine. He calls the book "fascinating" and then goes on to say in part:
"It takes an outstanding writer to bring an unexciting topic to life, and in this era of hype-ridden tomes about Java, open source software, Microsoft lawsuits, Year 2000, and .com 'best practices,' I was frankly skeptical about staying awake through a book on software requirements. However, Kovitz pulled it off in a way that's thorough as well as captivating, with copious examples.
"Part 1 of Practical Software Requirements begins by trashing the applicability of functional decomposition to non-trivial software projects, lauding instead design patterns and pattern composition/decomposition. It's an excellent beginning, and leads well into a discussion of the differences between requirements that address an issue from the customer's problem domain, and design specifications that discuss how requirements will be translated into the computer's software domain. He spends a lot of space discussing how to best frame a problem and how to handle problems with requirement multiple problem frames.
"I recognized some of my own past work in Kovitz's lessons, and most developers will as well. If you're responsible for creating software project requirements and want to ensure that someone actually reads and uses these documents, this book is for you."
In October, Jason Bennett, of slashdot.org, posted his perspective on Practical Software Requirements. The full review may be found here.
"Breaks down the legalistic view of requirements engineering as a top-down fill-in-the-blank exercise, and instead advocates a more flexible system whereby the design is kept separate, but each project has the process attuned to its distinct needs. This is quite a refreshing view, but one that still mandates good software engineering practices that can get any project off to an excellent start."
The August, 1999 issue of Dr. Dobb's Journal contains a solid, concise review written by Gregory V. Wilson. The review is also posted at their well respected web site, Electronic Review of Computer Books. An excerpt is quoted here:
"Kovitz starts by demolishing 'the myth of functional decomposition' (which is actually the title of Section 1.1). As he points out, a good engineer is one who knows a lot about problems that have been solved in the past, and can use that knowledge to figure out which of those proven solutions should be applied to the present problem. Defining a problem's requirements is therefore really about gathering the information needed to choose, and customize, a solution (or set of solutions).
"All of this is good stuff, and I learned quite a bit from the first few chapters of this book -- especially Chapter 5, which describes five common kinds of problems, and the sorts of questions that a requirements document should answer for each."
"This book explains how to write documents which describe software requirements comprehensively and correctly."
Full Review Available at Clipcode.com
In the May, 1999 issue of Computing Reviews, P. Abrahams calls the book "pragmatic and helpful," and writes:
".... In this fine book, Kovitz opens his discussion of software requirements by arguing that the usefulness of functional decomposition is a myth--that it provides virtually no helpful guidance either in figuring out how to build a system or in stating the requirements for building one...
"In a field that has been driven by rigid methodologies, it is a pleasure to read a book that takes a practical, undogmatic approach to developing the requirements for a software system...
"A nice feature of the book that relates principles to reality is the fourth part, 'Examples,' which presents the requirements and user interface documents for an actual program... The example is large enough not to be a toy, yet small enough so that one can read and understand the relevant documents without becoming lost in a mass of detail.
"The book is well organized, literate, and readable. In a field where rigid prescriptions of methodology are the norm, a relaxed yet eminently useful approach to creating software requirements and specifications is a delightful discovery."
In the August 1999 Requirenautics Quarterly, a publication of the Requirements Engineering Special Interest Group of the British Computer Society, Bashar Nuseibeh writes:
"I found Kovitz's book a pleasure to read. I believe that it is a 'must buy' for all software development practitioners with a serious intent on applying both novel and established techniques for requirements writing. It does not try to cover many worthy requirements engineering topics and practices, but instead focuses on presenting a pragmatic approach to solving the very real problem of expressing software requirements. In doing so, it provides a valuable service to the community and is an excellent addition to the requirements engineering literature."
Here are some other endorsements of the book:
In C Vu, a Journal of the Association of C/C++ Users 11-2 (January 1999), Francis Glassborow writes in part:
"If you need to prepare requirements documents or provide guidance to a neophyte, this book will be well worth its price. If you write software without these documents, read the book and decide whether you shouldn't change your working practices."
Recommended by Microsoft to study for technical exam 70-100:
On the comp.software-eng recommended reading list:
"Full of good things -- insightful and substantial."
--Michael Jackson, creator of JSP and JSD
"Finally, down-to-earth, usable techniques to replace the top-down myth! Readable, stimulating, reveals the fun side of requirements."
--Jay Miller, Sun Microsystems, Inc.
"A well-written book -- it includes many useful ideas ... A welcome, fresh look at problems often introduced by industry buzzwords."
--Haim Kilov, Merrill Lynch
Requirements template sent in by Karen Castle, Delta-v Technologies, Inc.
(Microsoft Word Document, 100 Kb.)