Software Requirements & Specifications by Michael Jackson

Selected quotes from
Michael Jackson.
Software Specifications and Requirements: a lexicon of practice, principles and prejudices
Addison-Wesley, 1995.
ISBN 0-201-87712-0 [ See this book at]
compiled by Tom Verhoeff in October 2003.


p. 1
"To develop software is to build a Machine, simply by describing it. This is one good reason for regarding software development as engineering. ... The parts of the world that will affect the machine and will be affected by it are its Application Domain. ..."

"This distinction between the machine and the application domain is the key to the much-cited (but little understood) distinction between What and How: what the system does is to be sought in the application domain, while how it does it is to be sought in the machine itself. The problem is in the application domain. The machine is the solution."

"An inability to discuss problems explicitly has been one of the most glaring deficiencies of software practice and theory. ... writers on development method claim to offer an analysis of a problem when in fact they offer only an outline of a solution, leaving the problem unexplored and unexplained."


p. 20
"Some years ago I spent a week giving an in-house program design course at a manufacturing company in the mid-west of the United States. On the Friday afternoon it was all over. The DP Manager, who had arranged the course and was paying for it out of his budget, asked me into his office.

"`What do you think?' he asked. He was asking me to tell him my impressions of his operation and his staff. `Pretty good,' I said. `You've got some good people there.' Program design courses are hard work; I was very tired; and staff evaluation consultancy is charged extra. Anyway, I knew he really wanted to tell me his own thoughts.

"`What did you think of Fred?' he asked. `We all think Fred is brilliant.' `He's very clever,' I said. `He's not very enthusiastic about methods, but he knows a lot about programming.' `Yes,' said the DP Manager. He swivelled round in his chair to face a huge flowchart stuck to the wall: about five large sheets of line printer paper, maybe two hundred symbols, hundreds of connecting lines. `Fred did that. It's the build-up of gross pay for our weekly payroll. No one else except Fred understands it.' His voice dropped to a reverent hush. `Fred tells me that he's not sure he understands it himself.'

"`Terrific,' I mumbled respectfully. I got the picture clearly. Fred as Frankenstein, Fred the brilliant creator of the uncontrollable monster flowchart. `But what about Jane?' I said. `I thought Jane was very good. She picked up the program design ideas very fast.'

"`Yes,' said the DP Manager. `Jane came to us with a great reputation. We thought she was going to be as brilliant as Fred. But she hasn't really proved herself yet. We've given her a few problems that we thought were going to be really tough, but when she finished it turned out they weren't really difficult at all. Most of them turned out pretty simple. She hasn't really proved herself yet --- if you see what I mean?'

"I saw what he meant."

Context Diagrams

p. 36
"It's good to draw context diagrams, but I think it's better to draw them with a different emphasis. I would rather think of a context diagram as showing the context of the problem, not of the system. That means above all that it should focus your interest on the application domain."


Critical Reading

p. 39
"Over 20 years ago, in The Psychology of Computer Programming, Jerry Weinberg wrote this about programming:
`Programming is, among other things, a kind of writing. One way to learning to write is to write, but in all other forms of writing, one also reads. We read examples --- both good and bad --- to facilitate learning.'

"... Nothing will improve your ability to write good descriptions more than the habit of careful and critical reading."

The Fudge Factor

p. 88

Graphic Notations

p. 90
"... good graphic descriptions are hard to make. For any description, graphic or textual, you have to decide what to show and what to ignore."

p. 91
"Graphic notations are, in fact, formal languages. Yet they seem to carry a higher risk of vagueness than textual languages. ... the cure for vagueness is not to avoid the use of graphic notations altogether. They're much too useful for that. The cure is to be very careful when you write a description in any language, and to be twice as careful if it's a grahic language."


"For software developers, mathematics is only a tool: not the whole of their trade, nor the greater part of it, not even the most important part. The central emphasis in software development --- especially in requirements and specifications --- is not on proof and logical deduction, but rather on separation of concerns and the clarity that makes a truth obvious. It is not on mathematical abstraction, but rather on identifying and describing the Phenomena of the Problem Context in which the machine must function. Above all it is not on calculation, but rather on description. Software describes a machine that must fit into the world of concrete reality, not into a world of Platonic abstractions and ideals."


p. 125
"The classical grammarians distinguished several moods of verbs. `You sing' is in the indicative mood: it asserts a fact. ... And `May you sing!' is in the optative mood: it expresses a wish."

p. 126
"It's not a good idea to introduce the uncertain linguistic subtleties of English verbs into system development documents."

"You can classify ... properties as indicative and optative. Indicative properties are those that the [problem] domain possesses regardless of the behaviour of the controlling machine."

p. 127
"Optative properties are those that the controller is desired to bring about or maintain."

p. 128
"Avoiding subtelties isn't the only reason to keep indicative and optative in separate descriptions. Another, equally compelling, reason is that the mood of a description changes during the project. The domain properties that are optative when the software is under development become indicative when the software is deployed. The machine interacts with the domain and --- all begin well --- turns our wishes into facts."


p. 149
"The mathematician G. Polya wrote an admirable book How To Solve It, in which he explains and amplifies ideas for solving mathematical problems. The ideas are wonderfully suggestive of ideas for solving software development problems. They come from the ancient Greeks..."

p. 150
"The Greeks were the first people in the Western world to think [write?] systematically about how to solve problems. Many of the words we use to talk about problem solving --- analysis, synthesis, method, system, theorem, heuristic --- are derived from ancient Greek words. The word `problem' itself is of Greek origin. It means something put forward, as a difficult question may be put forward to be answered.

"The Greeks divided mathematical problems into two classes: problems to prove and problems to find. A problem to prove requires the solver to prove something. ... A problem to find requires the solver to find or construct something. ..."

"Each kind of problem has its principal parts related in a characteristic Problem Frame or structure, and a solution task posed in terms of those parts. The principal parts of a problem to prove are the hypothesis and conclusion. The solution task is to demonstrate that the conclusion follows from the hypothesis --- or, perhaps, that it does not."

"In a problem to find, the principal parts are the unknown, the data, and the condition. The solution task is to find the unknown, which must be of the right kind and related to the data by the condition."

"Given a particular problem frame, ..., you can begin to talk about general Methods for solving problems of the class that fit the frame. Polya gives many recommendations. For problems to prove his suggestions include:

"For problems to find, he suggests:

"All these recommendations are given in terms of the problem's principal parts. Without the problem frames and their named parts you couldn't talk about problem solving at all in such general terms."


p. 187
"Ken Orr --- of the Warnier-Orr method --- tells a delightful story about Barry Boehm and the intangibility of software. Barry was working, many years ago, on the avionics software --- written in Fortran --- in a project to develop a new aeroplane. The weight of the plane was critical, and the project director had appointed a weights manager, whose job was to ensure that the total weight of the plane's components did not exceed the design limit. The weights manager came to Barry to ask how much the software would weigh. `Nothing,' said Barry. `That's ridiculous,' said the weights manager; `the software is costing a million dollars and doesn't weigh anything? I don't believe it.' But Barry insisted. The manager went away. Next day he returned, triumphantly holding the punched-card deck of a Fortran program that he had picked up in the computer room. `Look,' he said; `here's some software, and it does weigh something.' Barry held on of the cards up to the light. `See those holes?' he asked the manager. `Those holes are the only part of the software that actually goes into the plane.'"


p. 193
"The terminology of software development is mostly in a chaos that correctly reflects the chaotic state of the field. Usage of the word specification is no exception."

p. 194
"I like to use the term in a much more restricted way. It's one of a trio of terms: requirements; specifications; and programs."

"... specifications are all about --- and only about --- the shared phenomena ... at [the] interface [between the machine and the environment].

"Requirements are all about --- and only about --- the environment phenomena..."

"Programs, on the other hand, are all about --- and only about --- the machine phenomena..."

p. 195
"A specification cannot be completely abstract because its ultimate subject matter is concrete [really?]. If you rely on too much abstraction in the wrong places your specification will be about an abstract problem, not about the real problem that your customer expects you to solve [unless your customer is a mathematician?].


p. 199
"There are two basic difficulties with top-down [design, as activity; not after-the-fact description]. The first is that for inventing or designing new things to be built ... top-down enforces the riskiest possible ordering of decisions. The largest decision is the subdivision of the whole problem: it is the largest in scale, and the largest in consequences. Yet this decision is taken first, when nothing is yet known and everything remains to be discovered: if it is wrong, most or even all of the work that follows will be wrong or useless. Even worse, if the decision is wrong you won't find out until you reach the bottom level, or until you write the code."

"The second difficulty is that the real world ... hardly ever has a single hierarchical structure."

"In short, my advice to those about to work top-down is like Mr Punch's advice to those about to marry: Don't."

Feedback on this page is welcome.