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.

It's Long!

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 necessary?

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:

Opening documents
Saving documents
Printing documents
Changing fonts
Basic formatting

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 itself.

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.