The title of this website changes daily!
Our new website is here
How To Write Specifications Part 1

Every diatribe on software engineering I've ever read contains a dissertation on why you should write specifications. And every programmer I've ever talked to agrees that his life would be a lot easier if he had a specification, or could find the specification, or the specification wouldn't keep changing, or the specification was more detailed, or the specification wasn't out of date, or the project manager would understand that you just couldn't whack in a new feature without modifying the specification. Not to mention the poor old client who's praying that his one hour meeting with the fast talking sales person and the $10,000 he's parting with will come to resemble what the company actually needs - it didn't the last time! Yep, it's a real problem. It's such an obvious problem that I won't spend one second more arguing that we all need specifications in order to go home at night to play a friendly game of Doom with our next-door neighbour.

But how, exactly, do you write a specification so that the client understands it, the programmers can make sense of it, the testers can test it, the marketing people can sell it, the final product resembles it and, most importantly, you don't go out of business writing specifications that no one ever pays you for? Hmmmmm.

Before I go any further, I should point out that I'm going to limit this discussion somewhat. I'm only going to talk about the types of specifications that are required to write one-off software solutions that will never be used for shrink-wrapped software. These types of specifications need to have a fixed price at certain stages and they need to be economical to produce. They can't rely on a vast amount of VC funding to keep the company afloat. Why? Because VC's don't like IT companies anymore and secondly, because even if they did, they'd be pretty stupid to invest in consultants who could only provide a fixed return for every dollar they invested. And lastly, if you're in the business of writing these types of specs, you'll also find that you probably win only one out of five jobs you apply for, so your submission system had better be efficient.

The first thing that you need to know about specifications is that you don't need just one of them, but three. And since everyone in the IT business seems to call these three types of specifications by different names, I'll be consistent and do the same. They are:

1. Functional Specifications
2. Design Specifications
3. Technical Specifications

Functional Specifications

What's a Functional Specification? Here's a Functional Specification for a transportation device:

Functional Specification for a Transportation Device

Can be used on inner city and country roads
0-100 kmh in 10 seconds
Manual, 5 gears
Seats 5
Economy better than 10 litres per 100 km
Leather seats
5 meter turning circle
CD player with boosters

As you can see, a Functional Specification is a short itemised list of features. And you usually come up with one in a 1-2 hour meeting when your smooth-talking sales representative or project manager, aka Mr Slick, first meets with the client. It contains no details, may be missing a few vital bits of information, but at least it resembles the post-it-note the CEO stuck on your client's computer. When Mr Slick gets back to the office he delivers the Functional Specification to your programmers and asks them to calculate a broad price range for the product. The programmers decide that the following choice will satisfy the client's requirements:

Photo courtesy of Monsieur Colburn

It's also clear that the following do not satisfy the client's requirements:

- CD player lacks boosters
- Turning circle too big
- Insufficient acceleration
- Lacks leather seats

Get the point? Our tiny Functional Specification has condensed a broad range of 'possibles' into a narrow range of 'maybes'. The unfortunate thing about the maybes is that the cheapest one costs $30,000 and the most expensive one costs $200,000. Isn't Mr Slick going to look stupid when he sends an e-mail to his client giving a maximum price range that's around seven times the minimum price range? Yep, he sure will be. And that's one reason why IT companies should only employ programmers to do all the important work because they'd never make that mistake, would they? Ooops. No, I didn't mean to say that. However, it is important that whoever visits the client finds out at least approximately what his budget is so that the e-mail back to the client will look something like:

Now, this email is a truly beautiful thing. It's beautiful because:

1. You've summarised all the client's requirements so he thinks you were listening to him.
2. You know the programmers can produce some sort of product within the client's price range.
3. It probably took them less than an hour to reach this conclusion.
4. The client understands how the project will proceed.
5. If possible, it shows the client what a similar solution looked like.
6. You've firmly convinced the client you know what you're talking about by creating a link to this web site.
7. It's as vague as a Derridean philosophy but you've got plenty of scope to sort that out in the Design Specification.

The client, being a perceptive little bugger, will probably notice one amazing statement in your email:

Price range: $50,000-100,000

How but how can the price range for software vary between $50,000 and $100,000!? How? Well, as a software developer, you know it can, and often does, and the only way to define a price accurately is to write a Design Specification. The problem is you have to convince the client of this because you don't want him thinking that you're a stark raving mad profiteer.

How do you do this? You might not have to. If you are dealing with a relatively simple job whose requirements can be precisely defined in a 1-2 hour meeting, you'll be able to estimate the price from your experience. What a boring answer, so let's look at the slightly more complicated instance.

When your client asks for a shopping site 'like' or a job site 'like' you've got problems. And your problem is that not even your most experienced programmer is going to be able to determine how long the job will take, not even by visiting the web site. Why? Because it just ain't possible without a Design Specification and an accompanying estimation technique. The client will not like this. So you can sooth his ill temper by showing him what a Design Specification is and telling him that a typical 'Screen' will take between 1-10 days to create, depending on its detail. Then you can show him a typical Design Specification with Screens that took 1 day to design and Screens that took 10 days to design so he has some idea of what you are talking about. What's a Screen? What's a Design Specification? How can you explain one to a client? Yes, well, you'll have to read the article on Design Specifications that comes next. And if your client doesn't cop that, then get him to read my article on the impossibility of estimating software from requirements.

I know, you can't wait that long. So, to keep you quiet for now, I'll give you an example why a Design Specification is imperative.

Imagine a Functional Specification for a business that contained the following requirement:

Tenancy to accommodate changing employee requirements

Programmer's view of suitable tenancy

Client's view of suitable tenancy

Surely though, an experienced programmer and sales person wouldn't get that wrong? Well, perhaps not with a house. So let's stop talking about concrete objects and consider the following excerpt from a Functional Specification of a Web Based Order System.

"The system is to have workflow"

Workflow? Does that mean approvers? How many approvers? Will approvers be able nominate further approvers? Will they be able to edit the form? Or perhaps just some fields? Will notification be sent to other parties when the form is rejected or accepted by a particular approver? Are approvers preloaded from a LDAP database? Or perhaps the Microsoft Exchange Address Book?

You get the point? Now, if you come up with these questions, you're lucky, because you will be able to ring the client to point out these ambiguities. But more often than not, they simply won't occur to you or your programmer. What do you do then? Answer: you can't do anything because you didn't see the problem. What an awful answer. Awful, but terribly accurate. Your Functional Specification is going to produce a price that's wildly divergent from the price you're going to calculate in your Design Specification and yes, you will look totally incompetent to the client. The reason for this is not incompetence though, and I'm going to discuss it at length in that article on estimating that I keep promising to write.

Now, to Design Specifications...

Top | Home | What Is Yart? | Mailing List | Yart Work | Contact Us