Smiley Happy Coder

Lyle Barras

Lyle is Smiley Happy Coder

Developing for the web since 1999, that's 16 years

A good specification in plain English

Let me take you back to America in the early 60’s. One of the most important men in the world at the time, JFK, petitioned the US Congress to put aside adequate funds in order to, in his words “Land a man on the moon and return him safely to the Earth.”
You could say that this was a specification. NASA was challenged to take a man from the Earth, to the Moon and back. This is pretty much a user story.


User Stories

Most projects, be it interstellar travel or building a new website, involve a lot of different people with all sorts of technical ability. So why do we insist on writing these massively complex specification documents that are confusing for everyone except the developer who wrote it. This is where User Stories come in.

What is a User Story?

A user story is a way of writing a specification in a non technical, but none less accurate or in depth way. The American public, effectively the customer if were sticking with the Moon landings as an example, hasn’t the first clue about building larger rocket boosters or the challenge of coupling two spacecraft moving at thousands of miles an hour in orbit of the Moon. Why should they? The understand that men will be transported to the Moon and back again.

Lets switch back to web development, I know a bit more about that than travel in outer space!
Lets say a customer engages you to build a new e-commerce website for their business. Does the customer need to understand the intricacies of creating an order object? Or just that items can be added to the basket? Do they need to know about recalculating basket quantities including rebuilding coupon code calculations? Or just that the user is able to update basket quantities?

I think you can see where I’m going.

Using User Stories we can draft a good quality specification that has just enough pertinent information to make it useful but not so complex as to baffle the customer.


The danger with User Stories is becoming too generalised within the story. Lets take JFK’s user story. “Put a man on the Moon”.

After a matter of weeks the Director of NASA contacts the White House to report that they are ready to perform their task, to “put a man on the moon”.
The President, half of the White House and various Generals from all branches of the US Military all travel to the launch site in anticipation of the making of history.
When the president questions the director of NASA on how they were able to come up with a viable plan so fast, the director replies, the specification was so simple.

The gathered throng of dignitaries all make their way out to a specially erected seating area, spirits are high and silence soon falls. The assembled crowd are all staring up at the huge wooden structure before them. Not wishing to question to intellectual prowess of the scientists and engineers at NASA, no-one utters a word. In the distance a man wearing a flight suit steps up towards the capsule. He forlornly looks up and waves at the visiting guests who applaud this brave, soon to be, national hero.

After what seems like an eternity the astronaut is secured into his capsule. The engineers and scientist all move back away from the structure in readiness for launch. The clock is started. As the seconds display zero there is a massive noise, not a noise that the visitors were expecting. More of a wooden noise, sounds of wood splitting under huge stresses. After what seems like an age the capsule leaves the launch pad. It rises at a frightening rate and soon disappears from view.

Once things calm down the President pushed his way through the crowd to the director of NASA. “You built a giant catapult?!” The director is shocked. At that moment the silence was broken by a voice coming over the tannoy “The capsule has impacted the surface of the moon.” The scientists and engineers all look very happy with themselves, whoops and high fives are exchanged.
The President, remaining silent throughout the launch does not look pleased. Red faced he shouts “Impacted? What do you mean impacted?”
The director looking startled replies “We’ve done exactly as you asked, we put a man on the moon”
“How do you propose that we get him back?” asks the president. The director quickly the folder tucked under his arm, he seems to read something to himself and then looks up. “You didn’t ask us to return him, you asked us to put a man on the Moon, which we have”
“But, he’ll die” sobs The President the realisation setting in.
“Oh, no need to worry about that, he suffocated long before he left the atmosphere.” replies the director. The President was a gasp.


Sorry if I disappeared into a bit of a work of fiction for a while but I think it illustrated my point.
The User Story in this case was “To put a man on the Moon” when in reality it should have been as The President originally asked.

Now I’d imagine that NASA had a much more detailed and well thought specification that was probably even signed off by the customer, but thats another post.

I hope my ramblings made some sense, while User Stories can be very useful, serving to simplify the specification process, care needs to be take to not over simplify.

  • Top