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.

  • Is this for you? Did the client request it? Are you expecting more developers to join the team?
    – JeffO
    Commented Jan 6, 2011 at 20:24
  • Its mainly to aid my development. Every now and then I get random finance guys telling me "oh we should do xxx or yyy" when we're already discussed it, then sometimes in some meetings people just suggest random features, worst part is, I never have a proper way of adding the extra features for extra charges because my so called spec earlier was just nothing but a summary! Basically I have most problems Joel Spolsky mentions in his article when you don't write a spec.
    – gideon
    Commented Jan 7, 2011 at 13:27

1 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.
  • +1 thanks for your reply. yep. I did read all 4 parts of Joels article. What about the whole screenie process, would I just create dummy (plain looking) pages and forms first? So that I know what I need to write? Or do I start writing?
    – gideon
    Commented Jan 6, 2011 at 19:34
  • Start with what you know. Keep it simple so you don't get bogged down making it pretty. You need someone else's help if you go down that road (it takes time you don't have). While pretty specs are easier to digest, you've got a lot of work ahead of you. Commented Jan 6, 2011 at 19:40

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.