How do I write a functional specification quickly and efficiently

Question

So I just read some fabulous articles by Joel on specs here. (Was written in 2000!!) I read all 4 parts, but I'm looking for some methodical approaches to writing my specs.

I'm the only lonely dev, working on this fairly complicated app (or family of apps) for a very well known finance company.

I've never made something this serious, I started out writing something like a bad spec, an overview of some sorts, and it has wasted a LOT of my time.

I've also made 3 mockup-kinda-thingies for my client so I have a good understanding of what they want. Also released a preview (a throw away working app with the most basic workflow), and I've only written and tested some of the very core/base systems.

I think the mistake I've been making so far is not writing a detailed spec, so I'm getting to it now.

So the whole thing comprises of

• An MVC website (for admins & data viewing)
• 2 Silverlight modules (For 2 specific tasks)
• 1 desktop application

I'm totally short on time, resources and need to get this done quick, also, need to make sure these guys read it up equally quick and painlessly.

• So how do I go about it, I'm looking for any tips, any real world stuff, how do you guys usually do it?
• Do you make a mock screenie of every dialog/form/page?

I'm thinking of making a dummy ASP.NET Web Forms project, then filling in HTML files in folders and making it look like my MVC URL structure.

Then having a section in the spec for the website and write up a page for every URL I've got with a screenie.

For my win forms app, I've made somewhat of a demo Win Form project, would I then put in a dialog or structure everything as I would in the real app and then screen shot it?

---

For some background into this question. I've always been a crazy jump-to-code kinda guy, which has worked OK, but for the app I'm working on, it's not only complex, it's for a very very reputed and large company and I have to get it right!

(And it has been going well so far, today I gave a demo of the preview version which a lot of people liked!! =D )

If I do get the initial design right I will also have a great business with this company, there are already many thinking about new "awesome" features which they're ready to pay for.

Answer 1

Did you read part 2 of the article or his sample specification? They embody a couple important principles when writing a specification.

• Don't overdesign. The purpose of writing the spec is to force you to think about important things like what happens when there's an error, and how you expect the user to interact with the system. You don't have to go into inordinate detail to get something you can work from. You do need details, though.
• It's about communication. The purpose of the spec is to come to a common agreement about what needs to be done. It's not an ironclad document that requires the force of law. It's a tool to help you better understand your client, and your client to better understand what you want to do for them.

The best advice is to write enough so that you are clear on what you need to do. If you have open questions, document them in the spec and get answers from your client. Once you adequately understand what's needed stop.

If you are not careful, the document will take on a life of its own. It should have one purpose, don't add anything to the document that doesn't fit that purpose. It should be easy to maintain. If you have your entire detailed class diagrams in there along with other details that really belong in a unit test, you will either abandon the document because the upkeep is too much, or you will never get the project completed.

---

About Writing

Writing for people is hard. In fact, the two hardest things about writing is knowing how to start, and knowing when to stop. In the beginning you just have to do something. My advice for dealing with these two hardest aspects is:

• Know your audience. Who is supposed to read the spec? If it's just you and the client, then that's who you are writing to. If you have someone responsible for testing, you'll have some notes for them as well.
• Start with the highest priority thing. While authentication is important, the login screen is probably the best understood piece most folks have to write. Instead focus on that feature that your users need most. You know, that part that makes them money and is the whole reason they need the software.
• Fill in details as the questions come up and you get answers. Keep things really simple with napkin drawings if necessary until the client is happy with the arrangement. It's important to know what information is involved and how they will use it.
• Stop when adding more doesn't add value. There are some details you just don't want in a spec. You need to know when you have the right thing. You don't need to know that there is a variable inside a method named "albaquerque". That's source code, not specification stuff.