in reply to Design Documents?

I agree with all that has been said heretofor regarding the technical specifications of the project. Something that also needs to be considered is the intended audience of the software. Who will be using it? If the product will have a visible frontend with a target user base it is essential to gather reqirements from the audience and draft a general design document from these requirements. After the requirements have been signed off on by the userbase, more detailed, technical design documentation can be prepared. Having this general design in-hand and signed off on by your audience will prepare you for the unavoidable eventualities of users who are dissatisfied with the product or claim that the product lacks intended features.

Replies are listed 'Best First'.
Re: Re: Design Documents?
by dws (Chancellor) on Aug 27, 2002 at 21:01 UTC
    Having this general design in-hand and signed off on by your audience will prepare you for the unavoidable eventualities of users who are dissatisfied with the product or claim that the product lacks intended features.

    That sounds you're preparing for war with your customers from the outset. Don't go there! Expect that they'll change their mind about things, and be prepared to adapt. Part of being prepared is being light on your feet with documentation, to minimize that amount you'll need to change when new requirements come in and you have to make changes.

    If you're concerned about schedule dissatisfaction, prepare a short document for each change request that recaps the changed requirements, and details the consequences (in terms of schedule and resources) of the changes. Get the customer to sign these.

    Or better, engage your customer more frequently, and have them help prioritize the list of what they want to see next. If you're following one of the Agile methodologies (e.g., XP), you'll be in a position to "release" fairly frequently. Giving the customer the chance to reprioritize lets them change their mind, and greatly reduces the chance of them coming back at you with a "this isn't what we wanted!" argument.

Re: Re: Design Documents?
by mjeaton (Hermit) on Aug 27, 2002 at 23:19 UTC
    After the requirements have been signed off on by the userbase, more detailed, technical design documentation can be prepared. Having this general design in-hand and signed off on by your audience will prepare you for the unavoidable eventualities of users who are dissatisfied with the product or claim that the product lacks intended features.

    While everyone's experiences will vary on this subject, this was the way it was done at a consulting firm I worked for. We tried to document everything up front (mistake #1), have the user sign off on them (mistake #2) and when the user wanted changes, the Project Manager had to say "You signed off on this...if you want changes it will cost you $x".

    The customers would typically piss and moan about this until the sales people (weasels) would buckle under the pressure and tell our boss to tell us just to do it. This of course would lead to projects being a) overbudget (internally we would mark these extra hours as "unbillable") or b) late.

    I am now pretty convinced that attempting to document things up front and having a user sign-off is not the way to go about things. They will inevitably want changes...oh...and they'll want the changes in the same amount of time as the original project.

    Granted, I will write up as much documentation as I need to get the job done, but that's about it. Luckily, as an independant doing mostly sub-contracting work, I can bypass most of the issues I've had in the past and focus on what needs to be done, not what a bunch of sales weasels want. I'm starting to see the value in what the Extreme Programming people have to say although I haven't had the opportunity to try any of it yet.

    mike
Re(2): Design Documents?
by FoxtrotUniform (Prior) on Aug 27, 2002 at 20:51 UTC
      After the requirements have been signed off on by the userbase, more detailed, technical design documentation can be prepared.

    Don't rely on the users to be any more prescient than the programmers. Rather than having them sign off on what they think they want ahead of time, work with them (or at least one of them, who becomes the users' representative to the development team) during the project. That way, when you discover that feature X will be N times more difficult to implement than you thought, you can ask them just how useful X would be, and whether it's worth it. Or the user will, after actually using the product for a little while, discover that one of the interface widgets they insisted upon is actually a pain to use. Better to find that before the whole user base starts to whinge....

    Moral of this story: Requirements change. Plan for it.

    --
    F o x t r o t U n i f o r m
    Found a typo in this node? /msg me
    The hell with paco, vote for Erudil!