Practical Software Requirements: A Manual of Content and Style

Practical Software Requirements reveals how to write the documentation needed at the very beginning of the software development process: documentation of the customer's problem, and specification of the software so that it can be programmed and tested, and so that the final user documentation can be written.

Whereas most books on requirements provide a recommended table of contents, a single one-size-fits-all approach to specification methods, and writing advice not going much beyond "Every page shall be numbered," Practical Software Requirements concentrates heavily on making the document comprehensible and useful to its readers. But describing requirements is difficult and tricky in most real-world projects; it's really a job of technical writing. As a result, many requirements documents go forever unread, even by the customers who sign off on them, because they're too difficult to understand.

Practical Software Requirements treats requirements and specifications as a form of technical writing. Description techniques are presented for a wide variety of different types of customer problems and software. Instead of a one-size-fits-all technique such as "data flows and functions for everything," numerous techniques are presented, suitable to different types of problems and software. Instead of putting software into a few broad categories, the techniques apply to small "problem types" that are useful for breaking down a wide variety of larger problems. Techniques are supplied even for the smallest details of the document:

• how to word individual requirement statements,
• how to write use cases, common types of ambiguity and
• how to correct them,
• how to write a useful definition, and more.

The basics of requirements are also covered, enabling programmers or managers or others who have stepped into a requirements-gathering role for the first time to avoid common mistakes.

Practical Software Requirements also includes two full-sized example documents from real projects, suitable for use as a starting point in writing new requirements. They're relatively small projects, but not toy projects. They're real, complete with the unexpected complexity of the real world.

Whether you're a programmer or project manager writing requirements for the first time-- or an experienced system analyst-- this book will help you do it skillfully and effectively.

What's inside:

• 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

Why don't people read requirements documents? That's the problem solved by this book by focusing on what belongs in the document and how to write it so people can read, understand and use it. With Practical Software Requirements, you will give programmers, testors, user-interface designers and tech writers all the information they need to do their jobs.

This fresh view of requirements injects new sparkle and usefulness into what is often perceived as a dull but necessary task. The book offers practical advice like how to word a definition, how to name states and events and even how to avoid boring the reader. It brims with a wide selection of examples - from embedded applications that control machinery to large business applications that direct human organizations.

Whether you're a programmer or project manager writing requirements for the first time - or an experienced system analyst - this book will help you do it skillfully and effectively.

Synopsis
By following the techniques in this book, it is possible to write requirements and specifications that customers, testers, programmers and technical writers will actually read, understand and use. These pages provide precise, practical instructions on how to distinguish requirements from design to produce clear solutions.

 From Requirenautics Quarterly, August 1999, by Bashar Nuseibeh:
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.