How much time do you devote to the design document(s) for your software?

Question

Obviously the size of the project you're working on will be a huge factor in how long you spend writing the design document/specification. But do you go through everything, picking out every tiny detail? Or do you take a more agile approach and start writing the software quite early on and solve the problems as they come to you?

I've always found that there's only so far you can go with designing. There will inevitably be some things that are missed, and at that point how well you can adapt to the situation means more than the specification itself.

Am I taking the right viewpoint on this? Is it actually an opinion, or is a perfect design spec always the best route to go?

Answer 1

It depends a bit on your target audience, but my experience ( more in small/medium scale development than very large scale work ) is that detailed design documents are arduous and boring to write, rarely read and tend to end up out of date by the time a project is delivered.

This does not mean that they are worthless - if you are delivering something for someone, there needs to be an authoritative and agreed statement of what will be delivered sufficiently detailed that everyone can point to it in case anyone is dissatisfied with the deal and say "this is what we promised" and evaluate it against what was delivered.

If I were setting up a company to build a product, however, I wouldn't worry so much about a detailed specification. I would want to document what we were going to do, but I wouldn't want to go into too much depth regarding how - that is the part that is most likely to change and leave the documents out of date and useless or even inaccurate enough to be actually obstructive. I would prefer to document the "how" stuff in code using whatever documentation format the language or IDE supports best, so that as the code changes it is easier to update the documentation at the same time. It won't stop it going out of date, but it will reduce it somewhat.

Ideally you would want a design document that could double as your manual when your code is complete, but I don't know of anyone who has managed that successfully.

Answer 2

It definitely depends on the size and structure of the project.

For client projects, detailed specifications are a must. I like to heavily involve the client during the design specification. This helps flush out extra considerations and It gives the client a better understanding of what to expect. There is usually a positive shift in attitude (towards time and pricing) after the discovery and specifications are complete. This also allows us to set milestones - and hit them - which is favorable for the client, and our development team.

For internal projects and fun side projects, I generally create a flow chart and feature list, then start hacking it together. In these instances, what I find more important than a feature spec sheet, is the actual UI. I'll wireframe the site on paper and do a simple UI build (html/css). This helps me think through the user experience, which I value more than specific features on my own projects. I can always go back and piece together features later.

Answer 3

Depends what you mean by design documents.

I spend 1/3 to 1/2 of my time writing down designs for the software I write, in a note book, sketching things out, figuring out algorithms, relationships, stories, etc.

I don't do this all up front.

I don't have a main signed and sealed document that I'm working from. I have in the past, and I never got any work done, because I was always waiting for some one to sign something off. That was more a problem with the bureaucracy of the company I was with than the concept of design everything up front, but I still prefer the more fluid/agile approach I have now.