Other Extreme Documents

My work environment goes more along the lines of Fire! Aim! Fire! and producing any type of document is very difficult. This culture makes being a consultant very difficult when the customer wants fixed bids! Can you say "feature creep"? To combat this tiny problem I've created four M$ word templates to address what I'm doing without slowing down the rate of fire. The four docs are: problem statement, requirements, change control, and proposal.

The first two docs should be written by the customer but usually are not. So I write them to show the customer what I think they said. They accept or modify the document as they see fit and the process continues until they accept the requirements document. At this point the stuffed shirt squad can begin talking about money while I go off and do my thing (ie implement the requirements)

The problem statement should be precise but should not be a treatise on the topic. If you can state the customer's problem in one sentence, then do so.

The requirements document should also be as terse as possible. My template is basically a two column table. The first column is wide enough for people to put their initials in. The second column is where you describe one feature of the program. For instance "All phone numbers will be stored as ASCII strings in the following format: AAAPPPNNNNEEEE."

The change control document is like the requirements document but it allows the customer to add new features after the project has already started. Again, the customer should probably be the one to write the document (they know what they want), but I usually end up writing these also. Once the cc is written correctly, the legume reckoning team can set the price and deal with getting the customer to pay.

The proposal document is basically a change control but it is initiated by me to propose a feature that the software needs.

The point of all of this is to spend as little time writing documents (which I don't really get paid for) and as much time as possible writing code (which I do really get paid for :) ). I'm often tempted to write grand tomes that describe every possible facet of a project. Unfortunately, every time I've produce grand UML diagrams, and huge functional spec the customer has either changed their mind about what features they want, or worse I've used up so much time that I only have a week left to implement all of the documents!

How does all of this relate to extreme programming? I'm not really sure, but what I know is that the customer would rather see a prototype of their solution ASAP than see a pile of paper (or word documents). But on the flip side you do need some reference to help you aim and a quick requirements document that the customer agrees with can really help, even if it gets thrown away after the first prototype. --JakeWatkins

After having written all of that I've had time to do a reality check. It would appear that all of these extra documents don't really have anything to do with XP. I also don't actually write the real documents, the templates I use are really just check lists that I fill in. The PMs are the ones who create the real documents.

So if formal requirements documents are not produced before coding, how can you do Fixed Bid Xp ? --JakeWatkins

You have to have the stories. Maybe we should accept that the stories are a requirements document, but they aren't very formal. How about: get the stories, estimate them, add them up, multiply by a suitable profit factor, bid? --rj

<i>Estimating based on stories is what we are essentially doing. It just happens to scare the business types, they want concrete requirements documents so they can tie everything down and prevent changes (or bill heavily for them). However my experience is that the customer almost never knows before hand what they want, only after seeing a prototype can they see *part* of what they want. This is one of the reasons I am pushing my team to adopt XP formally. It works better with our customer's Fire Aim Fire type environment.

Of course the difficult part is determining the "suitable profit factor" :). I'm working on setting up a xp psp so I can have some actual metrics to base my factor on. I'm figuring that I should have usable statics in about six months to a year. In the mean time a good guess will have to work :). -jw</i>

I'm of the opinion that fixed-price software development contracts are always a sucker bet for one of the parties. Without a detailed spec, the developer can't scope the project well enough to avoid bidding below his cost. With a detailed spec, the customer gets exactly what he asked for up front, which usually turns out to be nothing like what he actually needs. Most of traditional software engineering seems to be about nailing down the spec well enough to ensure that the customer is the loser. --JohnBrewer

I second that opinion. I worked for a decade on government contracts, which are invariably fixed price. This leads directly to BigDesignUpFront, and everyone unhappy in the end. The only fixed price contracts I worked on that were successful were those where I was able to work directly with the customer to clarify and change the spec as the project evolved. Those were far and few between -- it takes a great deal of courage for both developer and customer to ignore a specification that is a contractual obligation. My advice: Stay as far away from fixed-price work as you possibly can. Convince your customer that he'll be better off if he can fire you at any time than he will by obligating you to give him whatever thing he guessed wrong at when the contract was let. --WayneConrad

I think XP is an alternative (IMO better) solution to the same problem fixed price projects try to solve: Risk. While fixed price projects have the problem that the customer and the developer are opponents (You know the picture where two people are saying "Let's build a house" and one (the customer) thinks of a palace and the other (the developer) thinks of a hut.), XP tries to get both parties to work together by balancing their responsibilities. --VolkerWurst

Exactly! YouCantElimniateRisk?, but YouCanManageRisk?. -- JohnBrewer