Now that we all know what a Functional Specification is and why you need one, it's time to
describe what a Design Specification is. You do know what a Functional Specification is,
don't you? If not, it's because you haven't read Part 1 of this series. So if that's the case
I suggest you go and do so
now. We'll wait right here.
The problem with terms like 'Design Specification' and 'Functional Specification' is
that everyone in the Information Technology business uses them to mean different things.
So I will start off by giving you an example of a Design Specification for something that
we are all familiar with - a 50-storey building.
A Design Specification for a 50-storey building would be the sum of the Architect's
Drawings, the 3D computer model, the humble Structural Engineer's Drawings, the Services
Engineer's Drawings and the Civil Engineer's Drawings. And, armed with this large lump of
paper, a builder could price a 50 storey building to within 1% of its final cost.
Wow 1%! That's pretty amazing, isn't it?
Not only that, the real estate agent could see how much lettable area he will have; the
tenant could see what the layout of their floor plans would be and even the window cleaners
would be able to tell if their multi-hoist scalable floor groper was of a suitable design
to traverse the curtain wall. You get the picture? The Design Specification will tell
everyone involved with the building exactly what they need to know.
Now, as far as software is concerned, the Design Specification is a document that should do
just the same. It should tell you enough to define a job to within 10%-30% (yes, I'm afraid it's
only 10%-30%). Note that I'm using the word 'define', not 'price'. Pricing a defined software
project is much more difficult than pricing a 50-storey building (believe me, I know, I
worked in the construction industry for 5 years) even if it does look like a simpler task.
And that's because software estimation techniques and, I believe, development tools, oops,
forgot to mention the IT Industry in general, are still in their infancy compared to the
10,000 year old building profession.
Enough babble. How do you create a Design Specification? The best way for me to
illustrate this is with an example, so have a look at the following Design Specification
for the Joke-A-Day Web
Site. Please go and read it
now or you will be
doomed to find the rest of this article quite meaningless.
I know you hate reading specifications, hell, who doesn't, but you'll notice that
the style I've used in the example is a breeze to read. And there are a few other things
to notice as well.
For such a simple web site, we have a nine page specification! Admittedly, there's
a pointless cover page, a silly disclaimer called 'Read This First', the content itself
and an Appendix of four pages describing what a Design Specification is. Is it all really
Yes it is. And it's not long. If you looked at a realistic specification that took,
say, two man-months to code, it would probably be over 50 pages
long. If you looked at the Design Specification of Microsoft Word it would, I'm sure, be
over 1000 pages long. And that's why we need all the apparently useless information at the
start. It eases people into reading a document they are probably going to spend the next
two weeks dissecting, commenting, criticising and improving. So you can only call us
thoughtful by easing them into the terrible misfortune they are going to have to endure.
Note that we didn't add a Table Of Contents to the Design Specification, but we
could have. I don't like Tables of Contents because in this day and age, because with documents
being searchable and heavily hyper-linked throughout, you just don't use them. Also,
I put an explanation of how the Design Specification is structured in an Appendix at the
end of the document, not the beginning, where you might expect it. That's because I hate
reading meaningless generic blurbs that I don't want to see after I've read them once.
It Consists Of Use Cases, Screens and Flows
After many years of writing Design Specifications that were either not read, not
understood or both, I've come up with the concept of documenting IT projects by
'Use Cases', 'Flows' and 'Screens'.
Use Cases give users an immediate understanding of a site in 1 minute flat. They are very
simple. A Use Case shows the different types of people who use the site and the actions they
can perform. Use Cases are great because users can understand the entire purpose of a program
and who uses it without ploughing through a whole heap of detailed information.
I like to keep Use Cases short and sweet and limit most projects to 1, maybe 2 and very
maybe 3 Use Cases at most. Once you've got the picture through Use Cases, you'll want more
detail through Flows.
The funny thing about Flows is that you don't theoretically need them. If you document a
software system by defining screens and how they interconnect alone, you will be completely
defining your program. From my experience, though, the only person who will be able to
understand your Design Specification will be you, the writer. Think about it. If you had
to read 500 pages of documented screens that weren't in any particular order, you'd have
to absorb them all before you could understand how they interact. If you were documenting
Microsoft Word that might mean that you'd only work out how to open a Word document by
selecting File/Open on page 363. That's ridiculous, opening a document is the first
thing you do! And let me tell you, that frustrates readers. That's where the flows come in.
You don't need them for everything, but you need them to describe that most common tasks
your program is setting out to achieve. Some more examples covering Microsoft Word might be:
Get the picture? You don't need flows for things like changing the Compatibility
Options in the Options screen. Who does this? Do you ? No, you don't. 99% of users
don't and that's why it's best to leave such obscurities hidden in the screen documentation
Flows should always be placed in the order in which users will perform the tasks
the system is designed to perform. This gets the reader off to a clear and logical start
as to where you are heading with the documentation. Flows should also be cross-referenced
to the Screen documentation so users can dive in to appropriate sections for detail.
My flows are pretty simple. They contain boxes to represent actions and diamonds
to represent decisions. Yes, I know, there is a whole language of flow chart symbols but
I have found these petty symbols to be quite sufficient for even very complex flow charts
(in general I hate complexity).
Having said all that, there are some instances when you don't need flows. If your Design
Specification is short and consists of say a set of simple web pages such as a home page,
a contact us page, a few other details that never change, then you probably have a system
that can be understood from Screens alone. But beware; as soon as your Design Specification
crosses a magical size boundary, or certain elements or web pages have state-changes
depending on users' actions, you'll probably need flows.
It Must Be Readable
Do you know who the most important reader of the Design Specification is? Is it
the CEO of the company you are designing it for? No, it is not. Is it the manager
who gave you the job in the first place? No, it is not. Then who is it?
Actually, it's the data entry person. Who? Deep down in the bowels of the organisation
you're working for there lives some poor unfortunate soul who enters data into an Excel
spreadsheet, perhaps a SAP system, perhaps sends emails to customers, perhaps compiles
monthly reports blah blah blah. Hell, there's probably not one of them, there may be 10 of
them. These poor souls are generally the only people who understand the business processes
in enough detail to criticise what you've done in minutia. Now of course the senior
top shot manager and CEO may glance over your Design Specification but guaranteed,
they will not understand the business processes you are automating as thoroughly as the
humble data entry person. That means the language you use in the Design Specification
must be understandable by non-technical people. In fact, whenever I develop Design
Specifications, I always insist that the data entry person is present at all of my
meetings so that I can be sure that the Design Specification will meet their needs.
The disclaimer I put on the first page of the specification and the section called
Read Me First are designed to reinforce the importance of the specification being
readable. Not to mention the chocolate frog perceptive readers can win simply by
doing your careful reading for you.
I also try to write in a Lite-n-Brezy writing style that's easily digestible.
If that sounds like a diet biscuit, it is. It's a diet biscuit for the brain that
allows you to easily absorb information. I'll be writing an article about the
Lite-n-Brezy snack pack soon, until then, consult The Transitive Vampire to improve
your writing style.
Initial Conditions Must State Loading Times
Look at this harmless statement:
Loading time is 2 seconds maximum using a 56k modem.
Harmless? Failure to apply this statement has resulted in more abusive clients,
attempted law suits and cream pies thrown at software developers than any other line
in the Design Specification.
Why? It is very difficult to estimate the execution speed of software prior to it being loaded on
production machines. In addition, it is often harder to estimate the speed of database operations
when you don't know exactly how big the live database will be or what performance degradation
will occur when a large number of users is using your system. Databases usually perform adequately
until the number of users builds to some critical point and the server can no longer execute
requests as fast as they are made. Techniques for determining production performance of code are
complicated and time consuming to apply so you'd better state them up front at this stage of
the specification. At the minimum, you should specify the execution time of code:
a) When the database is fully loaded.
b) On machines with the minimum CPU and memory that the application
is expected to run on.
c) In a production environment. Note that many applications
perform faster in a development environment that has a weaker CPU than a
production machine because resources aren't shared across as many applications.
If The Backend Isn't Readable, Who Cares?
You will notice that I have completely contradicted everything I've said about
readability in the section entitled
Joke-A-Day Web Site Administration Module Home
Page by launching an XML document on the reader. But that really is OK, because
the accompanying Design Specification XML Schema Administration System Design
Specification goes into lots of detail about just what it is. I often find this
happens for my 'backend' specifications where the client doesn't really HAVE to
know how he can administer the system being designed provided it produces the results
the rest of the specification describes.
How Long Does It Take To Write A Design Specification?
How long does it take to write a Design Specification? Why, that's easy. 2100 words at 300 words per hour equals seven hours. Right? Wrong. Design Specifications usually require at least 5 iterations. I've been involved with Specifications that require up to 10 iterations. And that's because as soon as you define a screen, you realise you're creating conditions, options and logic that need to be defined in yet more screens. A good rule of thumb is to allow every page to be completely re-written 2-3 times. You will find that what usually happens is this:
1. Meet with client and jot down some requirements
2. Go home and define the Screens for the requirements you obtained in Meeting 1
above. This usually takes twice as long as the client meeting to obtain those requirements.
3. Client is sent your Screens.
4. You meet with the client to overview the screens.
5. At this point, you will probably rewrite what you produced from Meeting 1 now
that the client has seen the implications of his initial requirements.
6. Client is sent your Screens.
7. You meet with the client to overview the screens.
8. You will probably rewrite 10-20% of what you last produced.
9. When the Design Specification is completely finished, you will probably
rewrite 10-30% of the Screens you have documented when you can see how they interact
as a whole.
As I said, prepare to rewrite at least 3 times. Call it a haphazard approach,
call it sloppy documentation, call it iterative design, call it anything you like but
I guarantee you this is what will happen if you follow the Screen and Flows technique.
Design Specification Will Always Miss Some Of The Detail
It's true. After all those meetings, after all those iterations, you will have omitted
at least 10%-30% of the details of the system you will end up delivering. Why? In reality,
software systems are state based. Here's an example of some state based systems:
- When you highlight a sentence in Microsoft Word and press the big fat B icon
it becomes bold.
- When you read an email its status changes to 'Read'
- When you order a book at www.amazon.com your order status changes to 'Pending'
Now what happens when you highlight a sentence in Microsoft Word, that was
in a table, in a document that was tracking changes? Would it be marked as a change?
Quick now. Don't know? What makes you think the Design Specification writer does?
The problem is akin to the story of Sher Khan who lost a lot of rice. Sher Khan
was an Indian king who was so thrilled by the game of chess that he ordered his army to
find the inventor of the game. The inventor, a man called Buddhiram, was produced before
the king - a simple-clad scholar who made his living by teaching.
"I wish to reward you for your wonderful invention. I am rich and powerful
enough to satisfy any wish you have," said the king. "Just name what you want, and you
shall have it."
Buddhiram was silent.
"Your kindness is most generous Sire, but first give
me time to consider my reply. Tomorrow, after I have thought about it, I shall
tell you what I want."
The next day Buddhiram surprised the king with a seemingly modest request.
"Sire," he said, "I would like to have one grain of rice for the first square
of the chess board."
"A grain of ordinary rice?" the king could hardly believe his ears.
"Yes sire, one for the first, two for the second, four for the third, eight for
the fourth, sixteen for the fifth and so on."
"Enough," the king was irritated. "I shall obtain your grains for all the
sixty-four squares of the chessboard as you wish. Every day I will double the amount
of the previous day. But such a request is unworthy of my generosity.
Asking for such a trite reward, you have shown me disrespect. As a
teacher, you could have shown more respect for your king's kindness.
Go! My servants shall bring you your sacks of grain."
Buddhiram smiled and went out.
At dinner, the king remembered Buddhiram, and inquired whether the 'insolent'
inventor had been given his 'tiny' reward.
"Sire," the chief court mathematician said, "we have worked from morning to
night to calculate the number of grains Buddhiram wants. It is huge..."
"However 'huge', my granaries can
easily stand it. The reward has been promised and must be paid," said the king.
"It is not within your power, Sire, to satisfy Buddhiram's wish. Your
granaries do not hold the amount of grains Buddhiram has asked for. There is not
that much grain in the whole kingdom; in fact in the whole world. And if you must
keep your word, you must order all the land in the world to be turned into rice fields,
then perhaps there will be enough grain to give Buddhiram.
The king was awe-struck. "Name this giant number, " he said thoughtfully.
"It is 18,446,744,073,709,551,615 sire!" the mathematician said.
A charming story you will agree. Pity it didn't attempt to describe the
number of permutations and state changes that can occur in Windows, Word or even,
dare I say, WinZip. I don't know if it's 100 or more than 18,446,744,073,709,551,615
but I do know that in any significant software project it's likely to be too large
to calculate and therefore impossible to define in a Design Specification. But the more
detailed your Design Specification is, the smaller that number is likely to be, even
if it always will be greater than 0. In fact, every attempt to define detail in your
specification probably removes ambiguity by a factor of 3 to 10.
Ok, that's it. That's all I have to say on Design Specifications for the moment.
So go off and write one and tell me how you go. Next come Technical Specifications but
I haven't written that article yet.