views:

153

answers:

5

Hi,

Yes we all get a warm and fuzzy feeling when we read about project specifications, and how they help keep a project on time and within scope etc etc.

Who here actually works for a company that keeps and up-to-date specification?

If you do, what are the reasons for this? Is the primary reason that you have a large team?

+1  A: 

If it's on a whiteboard where you have your team meetings, you're golden.

le dorfier
+3  A: 

Cor.. What's a project spec?

We tend to start out with an idea that has well defined timelines etc. then the sales team talk to the customer and promise the Earth. Our project spec then goes out the window!

So, we do not maintain a project spec mainly because:

  • Sales promise too much.
  • We have a small team and not a lot of time can be taken off coding for documentation.
  • We often have to turn around any changes VERY quickly (often ASAP), which leaves little/no time to update any documentation if there were any!

Do I think all of this is good? No! But at this time, it's hard to see a way out of it for us! Lots to do (both work wise and process improvement).

My home projects seem to be much better, but my specs are also a lot looser, and I know how I work - I therefore can gear the process to work much more in tune with me.

Rob Cooper
A: 

The best way to do this is to extract out the relevant bits of the func. / design spec. and then include them as "headers" in the actual code.

These headers can then be extracted using Javadoc or some such.

That way developers can update the "header" when they update the code and it keeps the whole project in synch.

Works pretty will for us.

nzpcmad
+2  A: 

If you use TDD, then you should have a specification that's always up-to-date by definition.

Rich Bradshaw
A: 

The very fact that project specs are so rarely kept up-to-date is a strong reason to reconsider their form, at least when they're presented as a printed document. My all-too-painful experience with such things is that they're usually out of date before they're even printed and distributed. Everyone thereafter is likely to have a different version after they've been hand-annotated.

What is the purpose of a "project spec" anyway? I guess it might include some or all of

  • Architecture
  • Business Requirements
  • Performance Constraints
  • External Interfaces
  • Legal Constraints

Potentially some more besides. Without going into the (dubious) wisdom of trying to fix all the above before coding starts, I'd be surprised if any of those categories did not change during the project lifetime, for any project large enough to have a specification written at all.

Is there any way that the requirements given could be delivered in the form of an executable test? If the requirement can't be expressed in the form of a set of tests that define its being met, then it's probably not a well-expressed requirement at all, and the spec is therefore incomplete.

I'm wondering if something like Ward Cunningham's FIT framework might not be a better way to do things? So the criteria are held in a Wiki, with the tests that define acceptance on the same page.

What kind of system or project would not be susceptible to that approach?

Mike Woodhouse