Practical Software Requirements
A Manual of Content and Style
Benjamin L. Kovitz
  • September 1998
  • ISBN 9781884777592
  • 448 pages
  • printed in black & white
This title is out of print and no longer for sale.

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.

Table of Contents detailed table of contents


1. Problem solving

1.1. The myth of functional decomposition

1.2. Problem solving and design patterns

1.3. Why software is hard

1.4. Pattern composition and decomposition

2. Problem defining

2.1. Requirements and design patterns

2.2. Software problems

2.3. Requirements engineering

2.4. Lessons learned

3. Two worlds and three designs

3.1. The problem domain

3.2. Requirements

3.3. Interface design

3.4. Validation of interfaces and programs

3.5. Description

3.6. Invention vs. validation

3.7. What software requirements are not

3.8. Summary

4. Problem framing

4.1. The knight’s tour

4.2. Domains

4.3. Shared phenomena

4.4. Connection domains

4.5. Realized domains

4.6. Frame diagrams

4.7. From diagram to documentation

4.8. Notation summary

5. Five problem frames

5.1. Overview

5.2. Information problems

5.3. Control problems

5.4. Transformation problems

5.5. Workpiece problems

5.6. Connection problems

6. Multi-frame problems

6.1. Combining problem frames

6.2. Inventory control system

6.3. Statistics package

6.4. Digital answering machine

6.5. Compiler

6.6. Electronic mail

6.7. Satellite reconnaissance


7. Software development

7.1. A division of cognitive labor

7.2. Analysis

7.3. User-interface design

7.4. Programming

7.5. Testing

7.6. User documentation

8. Two documents

8.1. Contents of a requirements document

8.2. Contents of a specification

9. Classes and relations

9.1. Two kinds of sets

9.2. Classes

9.3. All possible values

9.4. Impossible values

9.5. Relations

9.6. Cardinality

9.7. Relations as attributes

9.8. Uniqueness and functional dependence

9.9. Queries

9.10. Naming classes, attributes, and relations

10. Sequences and events

10.1. Structure

10.2. Events

10.3. Event responses

10.4. More sequence notations

11. Causation and control

11.1. State transitions

11.2. Actions

11.3. Dependency

11.4. Flow

11.5. Rules

12. Special topics

12.1. Elicitation

12.2. Object-orientation

12.3. Use cases and feature interaction

12.4. Reviews

12.5. Requirements jargon

12.6. Cutting corners

12.7. A few good books


13. Documentation

13.1. Why document?

13.2. Broad principles

13.3. Decoy text

13.4. More common mistakes

13.5. Poor uses of documentation

14. Organization

14.1. Content first

14.2. Grouping

14.3. Sequence

14.4. Emphasis

15. Small Details

acronyms "affect/effect" "always" assumptions

"click on" "compose/comprise" conventions "correct"

cross-references "data" definitions dependencies

document titles "entry" fancy cover first sentence

glossary "i.e./e.g." "invalid" metatext

"model" page layout "paradigm" "represents"

requirement statements tables title page "type"

underlining "use" "valid" voice


16. Bug Log requirements

17. Bug Log user-interface design



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

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.