Practical Software Requirements: Manual of Content and Style (PowerBuilder Developer's Library) [Paperback]

Most books focus on a method of analysis (usually one that translates neatly into a software development methodology) but can be totally incomprehensible to the poor end-user who is supposed to understand and approve the project. I've seen a number of attempts to remedy this: the most promising was to create the user manual as the first step in the requirements process. Tempting, but there are dozens of decisions in most business applications that need to be exposed up front but don't belong in user documentation--error messages, to give just one example.

Kovitz takes a different approach: he focuses on what needs to actually be in the text of a requirements document to make it effectively understood by both developers and end users. This is, as the subtitle makes clear, a manual of content and style. The focus of the book is how to present the results of your analysis rather than on how to conduct the analysis itself. As a result, this book contains useful advice whether you use SA/SD or the latest object-oriented methodology.

The first third of the book is devoted to determining the scope of the problem to be solved. Kovitz's approach is heavily influenced by Michael Jackson's Software Requirements and Specifications--another book I loved but sometimes found difficult to make practical use of. Jackson devotes a fair amount of his book to the topic of framing problems and how to fit your method to the problem, rather than distorting the problem to fit the method. Kovitz takes this a step further by describing in detail five common types of problems solved by software systems, outlines the different information required to solve each kind of problem, and shows how multiple kinds of problems can be solved in the same information system.

The next section details means of describing the information contained in a system, event sequences, and causation and control patterns.

The book finishes up with a section on wirting style and sample requirements and specification documents so you can actually see his advice in use. The documents come from a real program and not some toy problem--and they're a lot clearer than anything I've read at work.

It takes a lot of effort to write clearly, and where requirements and specifications are concerned, it's perhaps vital to the success of the project. Understanding and applying the advice of this book can probably do more for you than attempting to apply the latest lifecycle methodology.

Of course, I always have been a sucker for good books on writing, and I guess that this gushing shows it, but still...

The book is about techniques for describing a problem to be solved by a piece of software without describing the design of software components. In other words, providing the information that the software designer needs at the correct level of detail, without trying to specify a software design.

Designing software involves joining informal, real-world problems to the formal world of computers. In the real world problems are messy, vague, and unbounded. Unfortunately, computers only solve problems that are well-defined, unambiguous and well-bounded. Requirements writing is the art of reducing a messy-real world problem to a neat, well-defined, unambiguous description which can be used to drive development of a computerized solution.

This is one of the first books to effectively bridge that gap. I say "effectively", because it is certainly not the first try--every software methodology has techniques for capturing requirements. However, the methodologies hopelessly intertwine requirements gathering with system interface specification and even system design. This inevitably results in requirements being given short-shrift.

Many of the techniques this book teaches are equally applicable to creating documentation for existing software. Every technical writer should learn to create models of the problem their software solves and then explain software functions using only the terms defined within the model.

I highly recommend this book. However, I do know some people who did not like it. If you find it disappointing, I suggest that you try practicing with one or two techniques, then give it another read. The ideas are often more subtle than they appear at first glance. Expect that you may need months to really absorb its advice.