Business Analyst Training

Requirements elicitation, writing, analysis, and modeling by IIBA Endorsed Education Provider.

www.requirementssolutions.com

Business System Analysis Bookstore
In Association with Amazon.com
Help PicoSearch
Free Business Analyst Skills Test for CBAP Looking for Business Analysis Training

Practical Software Requirements: A Manual of Content and Style

Buy the Book
Summary TOC Back Cover Author Look Inside Comments Reviews
Benjamin L. Kovitz
October 1998, Manning Publications Company, Paperback, 444 pages, ISBN 1884777597


Summary
Buy the book

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
 
analysis bookstore top
BA books: Table of Contents
Buy the book

PART I GROUNDWORK


Chapter 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

Chapter 2 Problem defining
2.1 Requirements and design patterns
2.2 Software problems
2.3 Requirements engineering
2.4 Lessons learned

Chapter 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

Chapter 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

Chapter 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

Chapter 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

PART II CONTENT


Chapter 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

Chapter 8 Two documents
8.1 Contents of a requirements document
8.2 Contents of a specification

Chapter 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

Chapter 10 Sequences and events
10.1 Structure
10.2 Events
10.3 Event responses
10.4 More sequence notations

Chapter 11 Causation and control
11.1 State transitions
11.2 Actions
11.3 Dependency
11.4 Flow
11.5 Rules

Chapter 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


PART III STYLE


Chapter 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

Chapter 14 Organization
14.1 Content first
14.2 Grouping
14.3 Sequence
14.4 Emphasis

Chapter 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

PART IV EXAMPLES


Chapter 16 Bug Log requirements

Chapter 17 Bug Log user-interface design

Glossary

Bibliography

 
analysis bookstore top
Back Cover
Buy the book

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.

 
analysis bookstore top
Author info
Buy the book
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.
 
analysis bookstore top
Business System Analysis Books: Reviews
Buy the book
Review-Date: 1/10/2005 Rating: 2 Summary: Up to chapter 3 and finding it useless

I have just finished Chapter 3 of this book and am near livid. The author has a confusing and abstract way of writing that is infuriating for those of us living in the practical world. The discussion regarding the intangibles of requirements and interfaces is a quagmire of confusing definitions. So far I have pulled nothing of use from these chapters and am more confused than when I started reading.

I am hopeful this all gets sorted out in later chapters because right now, this book is proving to be fairly useless at teaching this software engineer how to properly gather and formulate a requirements document.

If you are into theoretical rhetoric, it‘s a good choice.


Review-Date: 10/5/2004 Rating: 4 Summary: Requirements and Specifications that People Read!

Writing requirements as a product manager has always been a black art to me. It‘s not impossible but it normally involves a lot of fudging and reading it always make me feel that there‘s something missing. I often end up putting specifications inside the requirements document. How do I make it complete without ending up writing the specifications itself?

Kovitz‘s Practical Software Requirements provides a clear and concise guide to writing requirements by looking at the problem of developing software. By examining how we frame a problem and its domains, the book explains how the reader can extract elements of the requirements and specifications documents and present them in a concise manner.

Throughout the book, he proposes how its content can be written and provides clear examples. His approach is direct and concise, and he teaches the reader how to write without any hint of legalese that permeate traditional corporate requirements documents. His examples are practical and he addresses common mistakes that writers make.

I‘ve thoroughly enjoyed reading this book, and it has been an invaluable tool in helping me write better requirements and specifications at work.


Review-Date: 3/2/2002 Rating: 5 Summary: A Terrific Book

This is a great book for anyone whose job includes:
* Business Analysis (for software)
* Application Programming
* Technical Writing

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.



Review-Date: 8/28/2001 Rating: 5 Summary: It all starts with requirements...

This is a well written book that will help you write better documents. In addition to defining: what are Requirements; who should read them; and how to write them, this book gives some suggestions on what should happen next (i.e., the _Miracle_Occurs_Here_ box that is inserted after Requirements and before Coding). I would recommend this book to anyone involved in the software development process. Especially those struggling to get to CMM level 2.


Review-Date: 7/31/2001 Rating: 5 Summary: great insights plus all the regular stuff

.

this tells you all you need to know about requirements.

indeed, it tells a lot more than that because it explains things not just state them.

it kills some urban legends and myths about requirements that everyone should know but most people do not. but then most people do not know what they don‘t know. scare your phb, impress your colleagues with your wisdom after reading this book.

if you work with requirements, software, systems engineering, and especially systems architecture you need to read this book. even if you have read others and or think you know all about requirements you can still learn things that you didn‘t know or why what you thought was true actually is.

this book would work symbiotically with the art of systems architecture by rechtin and maier. read them both.

. .




Review-Date: 12/16/2000 Rating: 2 Summary: Theoretically nice but not practical

A nice theory approach to writing requirment specification but hard to put into practice. Good for someone already have lots of experience in writing requirement specification and need something from different views. If you are looking for a book for content and style in requirment spec, I don‘t think it helps. Besides, I do not like the author‘s keeping saying "and so on.... so on." Give me an example and don‘t say ‘so on‘ all the times.


Review-Date: 5/9/2000 Rating: 4 Summary: Great book, but lacks examples

Although it is titled as "Practical", the greatest problem of this book is the difficulties to put the methods it suggests into practice. At least, an example for each problem frame, but this book has only one case study that covers the information and workpiece problem frames only. Nevertheless, this is a great book that takes a radical approach to requirements analysis. So I give it 4 stars.


Review-Date: 4/19/2000 Rating: 4 Summary: Methodology elsewhere; style and content here

Deep and unique – I feel I‘ve really come to understand what a requirement is and how to communicate it to non–technical people. The reader, however, will have to be familiar with the concepts and terminology of software engineering or will miss some of the theoretical points. The only drawback for me, was the concentration on Jackson‘s approach. While the book ties the subject matter well to methodological components, I would suggest getting your methodology education elsewhere. Skip the theoretical "why", chapter 12 and beyond (Part III on style) is where the value of the book lies and justifies the cost.


Review-Date: 3/22/2000 Rating: 4 Summary: Making requirements look exiting!

Very inspiring book on what software requirements are about. What always seemed to be dull, became very much alive. Practical guidelines, stuff to think about in the ‘problem frames‘. Nice example of requirements and specification doc. Missing: elicitation – how to get information from the customer about his/her requirements.


Review-Date: 2/16/2000 Rating: 4 Summary: Good for experienced practictioner

I enjoyed this book and got a lot from it, Kovitz focuses not on a standard "join the dots" methodology but rather on outlining an overall approach followed by good detailed advice on possible analysis/documentation techniques and how to write clear, concise requirements. Hence I would say that its best for the experienced analyst who is already familiar with the concepts and various techniques described in section 2 and knows when to use/ when not to use them. He is truthful in what he says about needing to adapt requirements style and content to what the situation needs but in some development shops you would need to be an senior analyst to be able to vary from their standards. I would recommend it for any analyst with 2+ years experience who wants to improve and polish their ability to write requirements/specifications


 
analysis bookstore top
 
Requirements
  Business Rules
Prototyping
Requirements Analysis
Requirements Definition
Requirements Documentation
Requirements Engineering
Requirements Management
Requirements Traceability
User Interfaces
Miscellaneous
Requirements Validation
  Acceptance Testing
Test Cases
Test Data Engineering
Test Planning
Testing Tools
Business Process Modeling (BPM)
  Data Flow Diagrams
Decision Tables
Process Analysis
Process Improvement (BPI)
Process Models
Facilitation
  Conducting Meetings
JAD
Miscellaneous
Data Analysis
  Data Models
Miscellaneous
NEW RELEASES
Business Systems Analysis
Best Practices
Interviewing Techniques
Methodologies
Problem Analysis
Request for Proposal (RFP)
Requirements Elicitation
Task Analysis
Unified Modeling Language (UML)
Use Cases
Workflow Analysis
Home Links CBAP Business Analyst Skills Test Business Anlayst Training Inquiry