Fog Creek Software
Discussion Board

Using English for Program Specs

In my Msc course the same statement is repeated as fact: 

You cannot use plain english for program specifications - it is too ambiguous.

In his guide to writing good specs ( ) Joel advocates not only using normal english, but a rather informal style.

What are your views on this?  Has anybody had success using Joels approach of an entertaining spec?

Ged Byrne
Thursday, January 10, 2002

I always use plain english. Also insert real life examples "stories" to create a general backgrounder on the subject. So it would read like I need to be able to control all the SAP data going out of this server to that Backup system and should be able to adjust my time table for the same.

It also helps giving credit to the intelligence of the programmers concerned. Read Joel again on the issue of hiring the right people.

S K Rao
Thursday, January 10, 2002

The spec has to be in plain english (or french, german etc) because its primary purpose is to communicate to your end users or customer what you intend to code. You need comfirmation that your understanding of the requirements is correct.

Thursday, January 10, 2002

Both assertion are correct IMHO. It depends of the context.

For functionnal specs (mostly business, user requirements, user case, user stories, etc.) Plain english (or other natural language) is excellent and usually enough.

In my experience, the big advantage of this approach is that both developpers and clients are speaking the same language, and so communication is facilitated (and ambiguity reduced)

For technical spec (eg: Traffic Air control, GSM telecom protocol, XML spec), human language can be too ambiguous. That's why more formal approaches are needed to complement it (like for instance UML)

As always, there is not a simple answer. The real question is : How risky for a speacific feature is requirement ambiguity compared to all the other factors of the project (time, feature, budget). Reducing ambiguity risk to the lowest level is costly and may not be justified.

Robert Chevallier
Thursday, January 10, 2002

This is one of the reasons why I like Object Role Modelling for data modelling and design.  Its both diagrammatic (for modelling) and is generated automatically in a formal english that natural english speakers can understand.

ORM consists of facts and constraints upon those facts.

Customer has Address, a Customer has at least one address.
Customer has PhoneNumber, a Customer may have many PhoneNumbers.
Customer is of Type (Company,Individual), Customer is of only one Type.

and so on...
You can show the client the diagrams, at least once anyhow, but for the most part they will just look like blobs and rectangles.  The formal english syntax, whilst stilted, can be used as the basis of testing assumptions and facts. That you can also stuff in as many examples as you like and that the examples can be validated against the constraints also makes it a real world solution for them, rather than something abstract.

It all helps that you can then generate a database right in front of them and they have taken part in the process.  Pair Modelling.

Simon Lucy
Thursday, January 10, 2002


Do you have any links where I can read up on Object Role Modelling.

Ged Byrne
Thursday, January 10, 2002

There's the Journal of Conceptual Modelling

Microsoft pretty much have this exclusively now.  Dr Terry Halpin, the creator of ORM and now an MS person, writes regularly there.

ORM is part of the new .NET Visio modelling tools but it will likely be ignored because its too good.  You should still be able to get the VisoModeler application downloaded from MS for free which is more than adequate.

Simon Lucy
Thursday, January 10, 2002

Oh and I forgot  Terry Halpin's repository of papers.

Simon Lucy
Thursday, January 10, 2002

Thanks Simon.

Ged Byrne
Thursday, January 10, 2002

In fact, Dr. Halpin has also written a good series introducing ORM in the context of Visio/.NET for MSDN. It starts at .

Mike Gunderloy
Thursday, January 10, 2002

It is my hope that someday, program specifications will become concrete (formal) enough that a computer program could read them and understand them well enough to build complex and competent software without human aid.

With that said, Joel's praise of informal style in a spec doesn't necessarily mean formal specs are bad.  Joel's aim is to reduce fatigue on the human programmer, and a formal spec will wear you down in a hurry.  The most formal spec of all is the code itself, and obviously, if code were easy to read, we wouldn't advocate comments.

Keep in mind that if an informal spec is also ambiguous, you'll need to look at the code anyway.  A spec should give you enough information to know how to use a given piece of code without problems, so if it's ambiguous, it's useless.  Did I pass parameters to this routine in the right order?  Hmm, can't tell...

Robert Chevallier says that reducing "ambiguity risk to the lowest level is costly and may not be justified".  I say that that cost would have to be high indeed, to outweigh the cost of someone using that code incorrectly, and having to spend resources to discover what is going wrong.

Paul Brinkley
Thursday, January 10, 2002

The reason we have a spec is that the source code has too many details and is too hard to read for ordinary beings, and we want a generalized view of what the program does. An added benefit is that changing the spec is easier (again because it has fewer details.)

The day when we can run our spec directly without writing source code, we'll have to invent a higher-level spec, which, in plain english, communicates the general idea so that everyone can understand it before they begin to write the real spec, which is too hard to change... and so on.

Just my HO.

Johannes Bjerregaard
Thursday, January 10, 2002

> What are your views on this? Has anybody had success using Joels approach of an entertaining spec?

Joel's article is about writing a functional spec (FS): a FS specifies what the program does, maybe the UI's design (UI appearance and behaviour) ... but not how the software is implemented (internal software and data structure).

I agree with using English (natural language) for a FS: text, and preferably screenshots. For example, _CityDesk for Geeks_ at looks to me like a great example of a FS (not that I have actually tried to implement a CityDesk from that FS).

Whether to make the FS 'entertaining' might depend... <g>

Then there are *other* kinds of spec., e.g. a software design/structure spec.: which define what the software is (not what it does), and which may be non-english (e.g. UML).

> The reason we have a spec is that the source code [...]

Note that a given functionality could be implemented by any number of differently-implemented programs (different software design/structure, same I/O): that's a good argument IMO for separating the specs (functional spec, and design/technical spec).

Christopher Wells
Friday, January 11, 2002

At work we produce a rather formal Functional Requirements Specification, which contain very formal English and Data Flow Diagrams.  It is very similar to the ones described by my course for the Stuctured method.

Its my opinion that these are not very successful.  They are usually very long and very very boring to read.  They are not updated are soon out of date.

The users nevers get to see these documents, instead they are shown a powerpoint presentation.

I should be producing my own for the first time in a few months time, and I feel that I would like to take the advice described by Joel. 

However, I am worried about peoples reaction.  For the users the incomprehensible functional spec seems to have the same position that Latin mass once had.  They like it because it looks impressive and mysterious, and really don't want to know what its all about anyway.

Ged Byrne
Friday, January 11, 2002

There is one drawback to the PowerPoint kind of presentation of a specification and that's that the audience tends to idealise what's being presented and to read between the bullet points.

Even if you make explicit what is implicit there's never any real record of it.

Its also true, I think, that the more polished the presentation of any kind of specification (which is a promise), the more likely it will be agreed with, regardless of the actual content.  I think there was a research study done on this and that even when formal documents had nonsense inserted into them many failed either to notice or admit to not understanding the nonsense.

I do like things like whiteboards that can give you hard copy, or the neverending foil on an overhead.  I like using some kind of conferencing system/bug tracking system to document the decision making process.

In the end any kind of functional specification is a sales document.  Its someone selling ideas and future stuff, the engineering specification, the response, is a promise by engineering to deliver 'this' .  But even given the promises, engineeering needs to be flexible enough to do it another way or even not at all.

Simon Lucy
Friday, January 11, 2002

If plain english is ambigous then lawyers and law-makers can't possibly come up with plain-english statements to write down formal laws. We know they "can", so that statement in my opinion is "invalid".

Lawyers in their attempt to be precise and eliminate ambiguity use language in an extremely contorted way.

And indeed language can introduce serious imprecissions when describing processes (ever tried to explain someone how to tie a shoe, without recurring to any graphical aid not even gestures?)

Language is unsuitable to explain highly metaphisical concepts, such as love (how would you explain what love is, in plain english, without recurring to lyricism or stupid cliches?)

But then again you can't run away from it. I don't remember its name, but there was a philosopher who strongly believed that language was the biggest barrier in philosophy, and tried to formulate philosophical concepts using mathematical simbols and inference rules. He failed misserably. His studies later became the basis for modern logic, discrete mathematics. I can't remember his name though.

For software specs though, plain english usually does the job pretty well.

Beka Pantone
Tuesday, January 22, 2002

Beka Pantone: "If plain english is ambigous then lawyers and law-makers can't possibly come up with plain-english statements to write down formal laws. We know they 'can', so that statement in my opinion is 'invalid'."

Program specs aren't written by lawyers.  With that said, specs written in plain English can often be adequately unamibguous.  But this isn't always true, especially for more complex blocks of code which may have many side effects, performance characteristics, etc.

Paul Brinkley
Thursday, January 24, 2002

Laws aren't plain english (they contain lots of jargon).
Laws aren't unambigous (otherwise we wouldn't need judges).

Thursday, January 24, 2002

Pen chodh

Thursday, October 2, 2003

*  Recent Topics

*  Fog Creek Home