"But when the team is committed to BigDesignUpFront, it can be a problem: Once it's written into the design documents, changing it later can fall somewhere between gut-wrenching painful and impossible." I've never seen this anywhere. It sounds like a strawman to me. ''And to me as well. On several of the BDUF projects I have worked on the engineering management (almost an oxymoron) decided that the requirements needed refining and the specifications had to be changed to reflect that. Everybody -- and I mean '''''everybody''''' -- was pulled back in to look at the requirements, specification, and design documents. Once the changes had been made properly everybody knew what had to be fixed and what could stay the same.'' ''I don't see what the Big Deal is.'' Seems to me like pulling everybody back in to look at the requirements, specification, and design documents is a pretty big deal, especially if it means you end up throwing out a lot of code that's already written. Too often, the people who write the spec think "it only took me five seconds to change one sentence of the spec, it should only take you five seconds to make the corresponding change in the code, right?" I'll go with "gut-wrenching painful but not impossible", making the "impossible" part a myth. '''''Hmm.''' If you have code that was created to meet a certain requirement and then you decide that requirement didn't actually describe the product to be built -- toss the code. Sorry, pal, but it just ain't gonna hack it. It is inconsequential how long a change to the requirements takes; the essence is that the proper requirement be captured so that the code can create the correct product.'' If the documentation is going to allow the wrong code to be built, why do the documentation in the first place? Build the code, toss the wrong code, and build the correct code. No need to spend time, money, and effort writing and maintaining documentation that is not of value. Unless the documentation will provide value, it is non-productive to generate it. ''Yet you don't mind creating wrong code in the first place.'' [There must be a BreakEven point where cost of documentation=cost of producing code which would determine the ratio of each. No documentation/specification at all means lots of trial and error code at y$ per hour, Lots of documentation that may need changing and code rewrites is also wasteful at x$ per hour documenting/design, so what is the optimum balance of time t(x):t(y)? 1:9, 3:7, 5:5 ?] Why is producing wrong documentation considered better than producing wrong code? To rephrase, if the documentation can be written correctly the first time, why couldn't the code? [Producing code that is NotQuiteRight and getting it in the hands of your customers, or bouncing off of a failing acceptance test, closes your feedback loop on the design. Producing documents creates artifacts which must be maintained separately from the working system; absent a customer story stating that they want these artifacts for some reason, perhaps YouArentGonnaNeedIt. SmallDesignAllTheTime seems more in keeping with agility. -- JonChoy] ''Thanks, but the agility thing has nothing to do with it. Propriety and correctness do. The people who don't want to create and maintain documents before they generate code are the same folks who have a lot of other sloppy engineering habits. These are the folks that document preparation weeds out. This is a Good Thing, because it's nice to filter out their, um, "work" before you start creating the real product.'' So writing a spec doesn't really have any measurable benefit, but only serves as a "You Must Be This Tall To Code" marker for a project? Why not simply choose your dev team better, and have them spend their time coding? Or instead of a large piece of speculative documentation, why not commission something more universally appreciable, like an epic poem, a traditionally-trimmed bonsai tree, or a musical composition? Each requires a similarly high degree of diligence and attention to detail. Trying to weed out subpar personel seems like an HR problem, and not one specific to software development methodology. Documentation should be communication, not a rite of passage. -- CodaHale ---- ''The people who don't want to create and maintain documents before they generate code are the same folks who have a lot of other sloppy engineering habits.'' Nice RedHerring. Plenty of people who do want to create and maintain documents before coding have sloppy engineering habits as well: * writing lots of code based on their BDUF before testing any of it. Sounds like a pretty sloppy practice to me... * designing software with complete disregard to the tools to be used to implement it (or test it, for that matter). Any other engineering discipline would consider this sloppy. ''It's not a red herring; it's a non-exclusive, factual, representation of what actually happens. I've been in this game for 32 years now and I think maybe I know what I'm talking about.'' ''Who is gonna be dumb enough to put a lot of time and effort into writing code that can't be tested? Nobody I know or have worked with in recent decades. Having a BDUF doesn't require doing a bunch of blind coding. That is a red herring of a red herring.'' ''Additionally, good engineering practices usually involve a top-down design with a bottom-up implementation, so testing occurs as each level of functionality is being built. You have to make the doors open and close, the lights flash, and the buzzers buzz before the whole machine is put together as an integrated unit. Testing occurs as the doors, lights, and buzzers are being manipulated through their individual driver code.'' ''And what's this crappola about designing software without regard to tools, blah blah blah? Where did that come from? What kind of buffoon pays no attention to his development environment? Code is designed to meet requirements, but its implementation is based on what will work in a particular environment. That's the only smart way to work.'' ---- The problem with a bad passage in a design document is it is 100% useless. At least in a bad module, there is a high chance of recycling some code. For example, the class may be scrapped but one of its methods was correct. I cant run 2000 NUnit tests against a flawed design document and instantly retest as changes are made to the document. I can in code. Code can include documentation, be very easy to understand and fully encompass all technical details unlike a document. Design evolutions/adaptations can actually be implemented, used and rolled back in code. ''The purpose of requirements document inspection (such as the FaganDefectFreeProcess) is to make sure that the errors in requirements are ironed out '''''before''''' you start designing anything, much less before you begin to write code. Writing code should be the tail end of the process of requirements, specification, architecture, and design. If you get to the point of coding and find out you're making the wrong thing then your process is so totally hosed you need to re-examine everything from the beginning. Oy.'' Except this one little thing: ''releasing software changes the requirements''. For business software, the customer doesn't know what they ''really'' want until they see something that is close. Then they'll turn around and have a better idea as to what they really need. Deployment feeds into the specification. Now, do you want a system that takes that and rolls with it, or do you want one that sticks its fingers in its ears and shouts "La la la! It's delivered, we did our part! La la-la la-la!" ''No, that isn't a change in requirements for the current product. That's customer discovery that applies to the ''next'' product. You've met the requirements that the customer gave you, so you can bill on that. If they want something different then they get a chance to create a ''new'' specification for a ''new'' product. Otherwise you have a constantly shifting target and you can never bill on your completed work. Ask me how I know.'' ''The other option here is continuous time and materials billing, so it doesn't matter how much nor how often the customer changes their little, um, "mind," because you just apply TheConsultantsMantra and bill for your labor and any hardware you've got into it. Cool.'' ---- See: InAllMyYearsIveNever