What Makes a Good Design Document? 461
dnnrly asks: "I've been writing software professionaly for a couple of years now for more than 1 company and I've noticed a recurring pattern: I get put on a new project that already has a bit of history and I get told to read the design documents and then implement XYZ. What happens is I read the document, find that it gives me a lot of information about certain aspects of the system we are building, but leaves huge gaps in others. We're going to be rewriting some of the procedures very soon and I'll be able to influence the software side so I wanted to ask Slashdot readers what sort of things have they seen in design documents that they've liked/thought are a good idea? What have they found works and what doesn't? If all else fails, where's a good place to find all this stuff out?"
"There's usually a very defined and rigid format for every design document and the writers have obviously tried very hard to make sure that procedure has been followed, generally leading to an almost unreadable doc or a design for the sake of it. Part of the issue is that these guys have written the design after 2 or more years exposure to the problem so they tend to forget just how much they know."
Existence (Score:2, Insightful)
Duh (Score:5, Insightful)
Writing a good design doc is mostly tedious work interspersed with lots and lots of communication with your programmers and customer.
-Erwos
Be agile (Score:2, Insightful)
I hate it when that happens (Score:3, Insightful)
All I can suggest is: keep a strict separation between features and implementation.
do some use cases that describe how the most important part (the user) will handle the program.
And think ahead, your designs will change while building/deploying. How are you going to accomodate that?
Design Document requirements: (Score:5, Insightful)
- Sitemap (web) or screen map (desktop app)
- Feature matrix with columns for features, rows for pages/screens and indicators where a page/screen has a feature.
- Detailed feature specs need to be written kinda like function documentation - "preconditions" that state what is expected as in the user is authenticated or the DB has products and "post conditions" that say what gets set or hwat the user can do.
- Style documents greated by graphics designers who understand the medium (web/Windows API/etc) are invaluable for refering back to when someone doesn't like a font size.
All this documenting is no fun, but it is more fun then dealing with the lake of the document.
Diagrams, for one thing (Score:5, Insightful)
If I have to choose between a 50-page design document and three pages of clear diagrams, I'd pick the pictures.
Audience == People (Score:4, Insightful)
Design documents should be easilly written and easilly updated. I prefer a text editor to something where I can have 'really nice' formatting. Its just easier and quicker, and that leads to the documents being more likely to be kept up to date.
If the docs aren't up to date, no matter how well written or well designed they are, they are misleading and unhelpful.
a good place to find all this stuff (Score:3, Insightful)
A good design document often duplicates the actual programming process. It starts at a high level (What are we trying to do? How do we do it?) and drills down to the level of what each function (or class method) should do. It should define acceptable inputs and outputs, both overall and for each method. It should also define the unacceptable ones. You should be able to generate the unit tests from it as well as the actual program.
It should leave room for changes if you find out that using methodology Bar to implement Foo doesn't work.
The Final Document should be based on a reading of the code, and any differences between that and the pre-code spec should be documented as to their cause.
Design documents become stale (Score:3, Insightful)
When first written, they are good and complete.
As the project moves along and the design changes, the design documents aren't updated. If you are lucky, new features will be covered in errata documents, but old features that were found to be not feasable remain in the document, without any indication of why they were removed from the project.
Interfaces (Score:4, Insightful)
Keep it current (Score:4, Insightful)
If you're really serious about having useful design docs, the only way to do it is to have a dedicated staff whose job it is to keep it current, accurate and useful. Coders are rarely good writers, and even if they are, it's almost impossible to get them to keep docs in sync.
My favorite design document . . . (Score:5, Insightful)
To be honest, I find that customers have a hard time visualizing how something will work unless they can interact with it. I'll take some internal design notes for myself, then whip up something and reiterate.
This approach doesn't work well with some projects, but for the small web applications I make it works great.
And tests, do not forget to write the tests! (Score:3, Insightful)
This will save you eons when you are actually coding. Way too many testers are still wasting their time with manually going through the ssame maotion again and again to make sure it all works as expected.
If your product has a UI (Score:3, Insightful)
If you don't have a UI, then start from the configuration file or command line switches, and do the same thing.
Then you're done. If you can't configure a feature, or can't trigger it from the UI, then it shouldn't exist...unless there are other interaction points.
If you have a network app, document the wire protocol, range of input values, and expected behaviors (of your app and its clients) and outputs.
If it's a distributed system, figure out the different states and document them.
It's actually a pretty simple, though tedious, process. Starting from the UI is a great place, because it shows you instantly how complicated your app is. If it's too complicated, this type of document will show that pretty quickly.
What Makes a Good Design Document? (Score:4, Insightful)
At least for most of the projects I've worked on.
Document the choices (Score:3, Insightful)
Instead, document why you chose PostgreSQL over [foo]. Why you chose to roll your own templating system. Why you fork off jobs in a separate process rather than doing them in one process. Why you wrote this particular thingy as a C extension.
Documenting that stuff will be helpful to folks down the road when requirements/environments/whatever changes and they wonder why things were done this way in the first place.
Re:Duh (Score:5, Insightful)
No, that's just it. People often ask the difference between a Software Engineer and a Computer Scientist. This pretty well covers it. Ideally, a Software Engineer is an Engineer like any other. A major portion of their work is designing and documenting. Like how a Structural Engineer would create blueprints. Also ideally, a Computer Scientist is a scientist like any other. He investigates the world of computer software - experimenting and recordign the results.
In the real world, the roles of both blurr into "the customer wants this, code it." But to live up to the title of Software Engineer, you need to be much more proactive and be very involved in the non-programming aspects such as requirements gathering, documenting, designing, documenting, prototyping, documenting, and documenting.
Re:Mythical Creatures? NOT (Score:2, Insightful)
Most Important part of Design Document (Score:3, Insightful)
After the design document comes (Score:5, Insightful)
No, I'm not kidding.
The design documents which have driven you mad probably weren't incomplete. They were probably quite complete design documents. But a complete design document isn't supposed to cover everything. If you had a design document that was fully specified in every significant detail, you could run the design document through a compiler and generate your code. (This isn't as far-fetched as it sounds; there are tools to automatically generate large amounts of code just from simple UML diagrams. That's an example of design documents being translated directly into running code.)
A design document can best be viewed as the development team's prejudices regarding the best way to solve the problem. There will be holes in the design document, mostly in those areas where the programming team doesn't really have a good grasp on what the best thing to do is.
A good design document is a like a good steak; they're best when served a little bit rare. You want to give the guy who comes after you a game plan, but you don't want to commit yourself to doing things in one particular way when you don't know if that one particular way is going to work. After all, once the design document has had every stakeholder sign off on it, going back to the drawing board and saying "uh, this isn't going to work, let's try something else" means all the stakeholders get back on board again. But if the design document has some room to move--what you think are "holes"--then that gives the programmers freedom to get the job done without having to go through the entire design approval bureaucracy again.
Most serious software engineering shops worship at the altar of requirements and architecture documents. Hackers in the trenches add the "this is how it really works" document to that list. There's nothing quite as valuable as stumbling across some prior hacker's notes when you're trying to grok the system.
Stop looking at the design document for the 'missing' stuff. It might very well have been deliberately omitted. Start asking around for the "this is how it really works" documentation, instead.
Requirements are the foundation! (Score:2, Insightful)
I think that most requirements gathering activities don't involve the right people. Most importantly, they should involve the developer. I have seen requirements sessions involving only the business analyst, an IT lead, and the project manager. They leave out the developer! Usually it is done because the developer is busy with other things.
If you leave the developer/programmer out of the requirements work, they never get the opportunity to understand the requirements and ask questions as the requirments are formed. If you do these two things, you will get much better designs.
in English (Score:3, Insightful)
Re:Audience == People (Score:3, Insightful)
For the record, I agree: Design documents should be easilly written and easilly updated. I prefer a text editor to something where I can have 'really nice' formatting. Its just easier and quicker, and that leads to the documents being more likely to be kept up to date...., but ability and common sense about what documents SHOULD look like is far less likely to be the obstacle than the policy governing design documents.
Your mileage may vary. Good luck! We're counting on you.
Don't document your code. (Score:2, Insightful)
Video game design documents... (Score:3, Insightful)
If the design document is underweight, it was good enough to trick the bean counters into giving up the first check. But you really can't use it to build test cases out of it since the developer can add or subtract whatever they want.
If the design document is overweight, you can build test cases with a fair degree of accuracy over the life of the project. The problem is that some developers will bristle at being held accountable for every detail promised and don't like their milestone checks being held up until they deliver the goods.
The ideal design document that lays out what to expect without too much overwhelming detail and the developer delivering to full spec on time probably doesn't exist. At least, not in the video game industry.
Software Engineering 2005 == Medicine 1805? (Score:5, Insightful)
I draw the analogy to medicine in the 19th century because at that time physicians were finally trying to investigate the causes of disease and developing insight that, more than a century later, would lead to their interventions improving rather than diminishing life expectency.
Nobody knows what "best practice" should be, yet we're codifying a process. The design document is one aspect of this process. Rarely is the purpose of a design document to convey design. Rather, it is a "deliverable" presented to a PHB or client as evidence of progress. To this end, the larger and prettier it is, the better.
Good requirements = good design (Score:3, Insightful)
A good place to look is "Software Requirements--Revision" by Alan Davis (1993). I don't agree with everything Davis has to say, but the book is full of good ideas and potential "gotchas" to watch out for. Another good reference is DO-178B, the guidelines used for the development and testing of safety-critical software in commercial aerospace applications. It is available from the RTCA [rtca.org] for about $50.
If you're doing an OO project, then you might want to look at Booch's book: "Object Oriented Analysis and Design" and the UML 2.0 specification .
But, most importantly, you MUST have some kind of design documentation (requirements, at a minimum) and that documentation needs to be flexible enough to accomodate changes without causing everything else to grind to a halt while the revisions happen. Expecting to get good software with inadequate formal documentation, minimal planning and insufficient requirements is why 70% of all commercial software projects end in failure (documented and published statistic).
Anyone who says you can do good software by shooting from the hip is nuts. And they don't work for me.
Re:Duh (Score:3, Insightful)
School is about learning the terminology and trying to get the most egregious errors out of the way, so that, after graduation, real work can commence.
Hate to Say It (Score:3, Insightful)
Read Wieger's Software Requirements [amazon.com] from Microsoft. It is a very good book to work on. Mainly, our process is:
At least that is what we try to do. Half the time, it is 'You bought what?'
Requirements Analysis (Score:1, Insightful)
Purpose
Requirements
Definitions
Business Rules
Use Cases
Wire Frames (UI)
All of the terminology within the document is non-technical and basically describes the said business process and the proposed technical solution. In my experience the clients always flip to the wire frames section of the document, since this is the easiest thing for them to understand (pretty pictures!). A wire frame is really just a stencil of a screen created in any modeling tool.
So now you must be thinking why is he mixing design with definition work? I'm sure some would argue that the wire frame need not be in the RA document, since this is really design. However, a client may find it easier if they can walk thru the use case while looking at a screen representation.
Once client sign-off has been obtained that's when we get into the fun design stuff. Depending on the said tasks complexity you can utilize UML to further document the process. Any design documentation will be separate from the RA documentation but it will accompany the RA document when handing off to a developer. To me the single most important design document is the class diagram, and depending on complexity possibly a sequence diagram. I use UML on an as needed bases, you'll never need it all, but pick and choose different pieces as you see fit.
The 5 D's of software development:
Discover (Business Briefs)
Define (RA Document)
Design (UML)
Develop
Deploy
Re:Duh (Score:5, Insightful)
A lot of the time, we just put diagrams that made sense to us, and that worked a lot better than trying to make proper UML documents.
You can't get blood from a stone (Score:2, Insightful)
1) A company has a business process that isn't working well because it is understaffed by poorly trained and unmotivated personnel
2) The company decides to automate the business process to make it "more efficient". In the project charter, they justify the project by promising further staff cuts.
3) A project team is formed, and the IT department interviews the poorly trained unmotivated users to gather "system requirements". Which end up covering only a small fraction of the actual business process because the users don't care.
4) The IT department realizes the project is hopeless, and uses lack of resources as an excuse to bring in "consultants".
5) The consultants poor concrete on the system requiremnts to avoid "scope creep", ensuring that the resulting system will be functionally useless.
6) The consultants carefully build a system that meets a minimal interpretation of the sparse requirements.
7) In testing it becomes obvious that the system meets the paper requirements, but is functionally useless to the actual users.
8) The IT department offers the consultants follow on work in return for helping IT blame the users. The users get a staff cut.
9) The system is declared a victory, and bonuses go to the executives who weren't involved.
10) The consultant is hired to fix the system, now called "Phase Two"
It should be flexible: Use Wikis (Score:3, Insightful)
Exactly. I used to work at a company that had a 50+ page document that was supposed to be used as a template for design documents - a sort of meta-design document, I suppose. Problem was that things rarely fit into their preconceived ideas. It definately led to unreadable documents. The other problem was that the procedure to change the design document was so draconian that everyone was hesitant to change anything even though it would become clear that things needed to be changed when the real world crept in. (BTW: this company allowed absolutely no prototyping prior to finishing the almighty design document - for those of us who like to prototype, it was frustrating)
I'm thinking that wikis are the best way to both communicate and develop a 'design document'. The design document should be flexible and wikis fit the bill. The design document should show the history of thinking about the design and again, Wiki's fit the bill quite nicely as you can look back and see the discussions that took place that led up to various decisions.
What you need is a Maintenance Doc. (Score:5, Insightful)
Design Docs tell the reader how you intend to build something. In many shops (depending on the SDLC version, if any, that they use), it has little value after the design review.
As a roving consultant, I've seen a lot of crappy documents and SDLC (et.al.) procedures, and what has the greatest value for the programmers who come later is a Maintenance document that specifies:
1. The overall philosophy of the design: Why specific design choices were made.
2. What things did you want to implement (and why) but were postponed to a later version.
3. What design decisions were specifically rejected (and the reason).
4. Where are the system's weaknesses?
5. What are the coding standards specific to this particular project?
The Maintenance Doc provides guidance to the people who have to work on this stuff after you're gone (and to you, unless your memory is perfect). More than anything else, they will need to know the why of the design, not the what.
In my perfect world, the maintenance doc would be the main appendix to the design doc.
However, in most shops, the SDLC & its policies & procedures will prohibit that, and usually acknowledge neither the existance nor desirability of a Software Maintenance Document.
Good Luck.
Wiki is your friend (Score:2, Insightful)
As another said, "All I can suggest is: keep a strict separation between features and implementation. do some use cases that describe how the most important part (the user) will handle the program."
Re:Design Document requirements: (Score:3, Insightful)
- add a button to screen A that does function X
- change the layout of screen B so that it shows ALL of the widgets in chronological order
etc.
To do that, you want to start off with a nice diagram of the screens showing which UI elements come from which classes/controls/include files/etc. so that you know where to go and start looking at code.
90% of software design is about putting code in the right place. That means architecture consists, mostly, of telling codemonkeys where to go and put their code. When an architect is attached to a project, they can tell the codemonkeys directly - 'make a class called Foo, give it these methods'. Once the architect's gone, and the codemonkeys are maintaining it, the design documentation is the only hint any of them will get as to where is the _right_ place to put code.
In those situations, nice block diagrams showing which bits of code make which bits of which screens can be a real help.
Re:My favorite design document . . . (Score:3, Insightful)
K. I. S. S. (Score:2, Insightful)
The bare minimum is often the best. So, include precise definitions of the interfaces that the code has to meet, including any tests that it must pass and the constraints within which it must fit.
If it is firmware, then hardware interface specs must be included as well as whatever interface the firmware must provide for other system code. Add to this performance constraints or requirements and you are done. Leave implementation for later.
If it is module constructed in isolation, again the interfaces must be clearly defined and performance requirements declared.
Constraints define the resources allocated to the code. Performance requirements are a sort of constraint on time and hardware allowed. There are also other constraints that are usually implied but not stated like how long the engineer has to implement, test, debug, etc. This is effectively a cost constraint.
Implementation can also be documented, but is not fundamentally a part of a design spec. Sometimes code comments can be enough. Sometimes a few notes about competing implementation ideas and why one was chosen over the others can be helpful, but not as part of a design spec.
Keep It Simple Stupid - define what the module(s) must do, what tests it(they) must pass and that is it. If you do this right, then the implementation can speak for itself.
Re:Duh (Score:3, Insightful)
Re: Duh (Score:5, Insightful)
The most important thing for a document is to communicate. UML is a very good way to communicate that sort of information (when everyone understands it). But it's not the only way. Use whatever's best. If a few lines of text on a scrap of paper, or an ad-hoc diagram you've just invented, will communicate better (with your memory, with your immediate colleagues, and with anyone who might be maintaining the system in future), then by all means use it! Anyone who insists on UML or whatever for the sake of it is missing the point.
The main problem with these methodologies is that there's no way to force people to think clearly. You can encourage it, certainly; you can make it easier to do, easier to communicate, and easier to spot its absence; but you can't force it. Following the procedure is no guarantee of clear thinking -- and it's that clear thinking which gets projects designed and built.
Re:RFCs are requirements documents, not design (Score:3, Insightful)
Go take a software engineering course. There's a lot of wisdom that's been accumulated about how to write reliable software, and while (IMO) about two-thirds of it is utter rubbish, one-third is really good advice. Learning software engineering is like eating pufferfish: really cool, but be careful what you swallow. You'll learn about requirements analysis, drafting a coherent requirements document, architectural analysis, drafting a coherent design document, interpersonal skills needed to get people to sign off on your ideas, time management, resource allocation... computer programming isn't the same as software engineering. Very little software engineering is concerned with computer programming--less than a quarter, in my experience.
It's a fun subject. It teaches you how to tackle big projects, and have a reasonable chance of success at them. 70% of all software projects fail, but the 30% which succeed include some of the most fun projects you'll ever see. Take a software engineering course. It's fun, and you'll be hunting much bigger game once you're through.
Now, that said... you ask reasonable questions, you get reasonable answers. Design documents aren't exercises in futility. In fact, they're essential. For any nontrivial software project, at least 75% of the codebase is trivial--and since it's trivial, that means there are a few thousand ways to do it. A design document lets the entire team know precisely how the trivial parts are going to get solved, so that the team can all be on the same page when it comes time to tackling the big stuff.
In a good design document, the hard parts are underspecified for exactly the reason you mention; you go through a lot of bad ideas on the way towards finding the Right Thing.
Design documents come in two varieties: the kind which is written by one person who has final authority, and the kind which is written by committee. If it's the former, the design document will have in big boldface letters at the header and footer of every page, SUBJECT TO CHANGE. If you've got one of these and your copy of the design document is more than 24 hours old, go check another one out of CVS. These design documents change very quickly as the development teams try different approaches. Unfortunately, the latter is more common--in which case just getting everyone to agree on the design document is a labor of Hercules, so usually the middle is left underspecified so that the programmers can do whatever the hell they need to do without needing to go back to the committee.
After the project's done, one day should be set aside to document "okay, now this is how it really works...". That document stays inside the engineering pit. When people need to learn how the package works, they read the requirements (to learn what it does), the design (to learn how the trivial parts work), and the How It Really Works (to learn how it really works).
Hope this sheds some light on the documentation issue.
Re:Testing the design -- traceability (Score:2, Insightful)
Document readable to other engineers (Score:3, Insightful)
A good design document should describe what you want to build, what you need to change in the existing system and what your dependancies are to name a few. It should spell out how you want to order you classes (UML!), most importantly how you will use the global classes (like an user class).
Therefore, if any one of your colleagues can read your document and think one of the following thoughts your document was a success:
"Oh Joe wants to use the user class like this, I guess I won't change it to stop that from happening"
"I don't think Joe knows that I'm building a Foo class since he thinks he's going to build one, I'll email him and we'll decide who's going to do it"
"I see that Joe has this great system designed, but he seems to be forgetting the requirement that we have to let the end-users configure it through the app and he's only using property files. I'll email him and make sure he didn't forget that."
"Uh... what the hell is Joe thinking, there's an existing class that does exactly what he wants to do, why did he waste his time writing this document?"
Re:Testing the design -- traceability (Score:2, Insightful)
I often consider code the "detailed blueprints" of a piece of software. To use the construction analogy:
An architect describes a new building at a high level. (high level design)
A civil engineer designs the building generating the blueprints (aka code).
Contructions workers implement the design by putting up the building (compile and run).
5 steps - untenable (Score:5, Insightful)
Skipping to point four for a moment: I would argue that the requirements should be expressed in the form of tests - functional, unit, or otherwise, and that these tests be executable. The design MUST therefore meet the requirements. This then means that point number three may or may not apply.
I agree that code is not design. Design is abstract, and code is not. And pure-code-no-design folks go overboard in my view, but if you can't have complete requirements (and you can't) then you certainly should document that which is not obvious from a structural breakdown of the code itself. Particularly, documenting risky or unusual features of the code, such as tortured relationships and their semanitcs. To me that is the limit. Document what is not obvious, do not document what is structurally implicit, or otherwise explicit. Documentation covers risk, and risk mitigation points (ie. person hours) are best spent making better software, except when documenting something that, if left unsaid, might lead other developers to an incorrect assumption or conclusion.
As to point number five, your experience may vary. In my experience, it's quite the reverse. But in the example I'm thinking about, we didn't have each individual designing - the whole team designed together, and the whole team coded and tested, and never alone. Also, design changes, or any changes to assumptions (or APIs, or etc.) were well published throughout the team, so that there was ongoing restatement of context. If anyone thought that something was an odd or interesting design feature/artifact, they mentioned it, and the author clarified it and documented it. I don't think having individuals altering design outside of a process of consultation is wise, and I think this "cowboy" flavour of agile developent is abortive and a throwback to no-process development. However, small teams that are engaged collectively produce, in my experience, excellent design. You then need to capture what is not obvious, or somewhat obfuscated, and especially capture assumptions.
Where ThosLives and I would agree, however, I think, is that you need to trace design aspects to requirements. You may not have final requirements, but you always have some, and you shoulnt' make design decisions without a requirement to trace to. In this sense, you absolutely must have tracability from requirement to design to implementation to proof (test). And if requirement can be expressed as a test (not all requirements can), then that is, in my view, the best way.
Re:Testing the design -- traceability (Score:5, Insightful)
When I use the blueprints for an automobile to build the automobile, I get something different than the blueprints. I cannot use the blueprints to emulate the functionality of the vehicle. The blueprints are instructions to build the vehicle.
In software, the design is the thing which tells me how to write the code (have you ever tried to read code and find out what the function is supposed to do? generally you can only know what it does, not what it's supposed to do. Sometimes you get lucky and the design is written in the comments, but that's rare; generally comments just say "we watch out for overflow here" or something like "use pointer rather than array lookup to avoud some tricky thing" - comments are usually descriptive of what is going on, not why). If I have a good design I can write it in any language and meet the same requirements. That's a good litmus test for software: if it depends on a language, it's not a pure design. If you have to figure out what's going on to translate into another language, you're in implementation rather than design.
I will grant, however, that there are some difficult situations when you have a requirement "you shall use language X for this project", or "we decided to use language X to meet these requirements" - what happens if that requirement changes halfway through and your "design" was language specific? You're hosed. Good designs are language transparent.
Remember, the goal isn't to produce an application, the goal is to meet the requirements. The design tells you how you are going to meet the requirements ("have a text grid input box" and, at the next level, "have a function that draws a text grid input box") and the code fulfills the design ("textgrid.draw()"). (Note that some design decisions become requirements for a lower level, such as function calls, interfaces, etc.). Code should only be implementation.
What about agility? (Score:4, Insightful)
I work in control systems. We have in-house motion control software that we use to do weird jobs. This software is not as featureful or complete as the packaged solutions, but it is cheap to deploy, and designed to be expandable and flexible. A project might entail anywhere from a few hundred to a few thousand lines of custom code that sits on top of the 30-40klocs of core code.
When a customer requests a CNC retrofit of an old or weird machine, they seldom have any idea how the machinist on the floor actually uses the equipment. They see the problem as a basic one--the machine takes too long at X or the machine lacks capability Y. The machinist is not really a programmer and isn't mentally prepared to make the leap to writing a specification.
The solution to the problem was for me (a programmer) to go into work with the machinist for a few days when the software was about half done and help him make the parts he needed to. Even though the software was incomplete, I could at least step around any immediate problem by throwing a little bit of prototype code at the problem and get the operator's feedback regarding the process as a whole and how it could be changed to make his life easier.
I guess the point I'm making isn't fully formed, but all this talk about design processes seems to be missing the essence of that project, which was only possible by allowing the sole user of the software and the programmer to spend time collaborating. For much of the coding, I brought my workstation to the factory floor and worked right there. It made testing much easier and let me ask the operator questions whenever an issue arose that hadn't been forseen by my boss or his when they planned out this task and designed the system. I would, of course, run major changes by my boss first, but he pretty much trusted what the operator and I were figuring out.
We've been providing custom software to this company for several years. It's pretty much run without issues and has saved them huge amounts of money, essentially by optimizing a handful of machines in there shop. The project would never have gotten off of the ground if we'd been caught up in these sorts of formal processes. We don't have the manpower, or the timeframe.
Re:5 steps - untenable (Score:2, Insightful)
Clear requirements are your protection against politics in the client's office, using your project as a stalking horse, and many other unfair surprises of the business world.
If you have responded to an RFP, the requirements process allows you to restate over-specific, vague, or non-optimal customar requirements into a form that is testable and clearly specifies the functionality that is to be encoded. You restate what the client gives you, and negotiate until agreement is reached.
You have to have enough requirements to specify the functionality that you are committed to providing so it can be verified, and not so many that you wind up with a government ashtray that does work but costs five times (or five thousand times) what it should because it is over-specified.
This presumes a process of iteration and clarification that may well continue throughout the development cycle, and may be formalized in a number of different methodologies. But the principle of agreeing on requirements and proceeding on the basis of the agreement is essential to any productive business process, no matter how iterative.
Re:5 steps - untenable (Score:3, Insightful)
But I also know that non-insistance on precise, predefined requirements got us lots of contracts; in especially the circumstances that our customer doesn't know exactly what he wants and that it is part of our job to find that out.
There are other ways than technical or functional requirement specs to bring this shared understanding in a contract and manage the risk for both sides.
Good IT projects don't react or ride the waves of change, they create them. And these are typically projects where one doesn't have functional requirements up front.
Re:Testing the design -- traceability (Score:3, Insightful)
Chris