This page describes my philosophy of planning and organizing engineering projects. It also presents a theory of why we hate to document our work and suggests various planning and organization techniques.
The key to success in engineering is planning and organizing. The key to planning and organizing is to produce to right kind and the right amount of documentation.
Why do we so hate to document our engineering projects? We know by bitter experience that not doing so leads to wasted effort and frustration, yet we still fail.
Why do we keep making the same mistakes over and over again, hoping that this time things will turn out differently?
In our daily life, we all manage small "projects" without any organization, documentation or planning. Consider getting to work in the morning; there are many tasks and a tight schedule. Some tasks can be skipped (second cup of coffee), some cannot (putting on clothes). Some tasks require advance preparation (clean clothes, gasoline in the car). Other tasks can only be done at the last moment (deciding on alternate route to avoid traffic jams.) If you tried to document every task, it would be a large and complicated document. It would also be shelfware (documentation that is left on the shelf and never used.) That's because we all manage to get to work just fine without any documentation - we keep it all in our heads. The same holds true in many other areas of life, from cooking a meal to raising a child.
The problem is that we try to apply these same unstructured ad-hock techniques to engineering projects that are too complicated for our minds to hold. Eventually some vital detail is missed and the whole thing comes crashing down around us. Sometimes we produce what we think is documentation, but not the kind of documentation that organizes our projects and keeps us from missing vital details. One reason why we have this problem is that our engineering schools don't teach us how to document our work. Engineering schools focus on small projects that a student or small group of students can finish in time to be graded. This leaves the students unprepared for the more complex projects they will face in the real world. If they are lucky, they will enter a corporate culture that teaches them how to document their work. If they are unlucky, they will end up in an organization that punishes them for planning and documenting, or one that puts huge amounts of effort into generating shelfware.
For twenty years, I have been thinking about this problem and refining my methods. I have worked for Parker Hannifin, an aerospace company where mistakes result in people being killed. I have worked for Mattel, where the only factors that matter are how soon you can get the toy into mass production and how far down you can get the per-toy costs. I have designed products that cost less than a dollar to make and systems that cost millions of dollars. I have seen projects where the same work was done again and again because there wasn't time to document anything. I have seen projects that cannot move because they are buried in useless documents. Through it all, I have learned that the right kind of documentation will greatly increase the chance of the project being on time and under budget.
The key to being an effective engineer is to solve the problems that cause most project failures - lack of communication and lack of organization. The key to communication and organization is documentation; the lightest pencil mark outlasts the most vivid memory. Organization, planning, and documentation relate to the concept of "coupling" in software design. If part of a computer program depends on the internal details of another part, the two parts are tightly coupled. If the two parts talk to each other through a well-defined interface that hides the internal structure of each part, the coupling is loose. When changes are required, tight coupling means that changes in one part may require matching changes in the other part, which will in turn affect other parts of the program. Loose coupling allows you to change one part without having to change the other part. This saves a huge amount of effort and leads to a better product. To make loose coupling work, you must define and document the interfaces between different parts of the program. All of this applies to hardware as well - it is just as important to document the interfaces between the hardware components.
Managing an engineering project is in many ways like building a house: You start with a contract (Project Document), what the customer can afford (Budget Document), and wants (Requirements Document). You then fill in details (Specification Document) and then start construction (Design Document and Implementation Document). As the house is completed, it is inspected (Acceptance Test Document) and any problems are fixed (Revision History Document). Finally, it is delivered. You can try to build a house or manage an engineering project without documentation, but don't be surprised if the debugging phase is ten or twenty times longer than you anticipated, and don't be disappointed when important flaws are never corrected. As we engineers like to say, there is never time to do it right the first time, but there is always time to do it over.
Here is a description of the documents I usually generate during a project.
THE PROJECT DOCUMENT Answers the question "Who does what and when will they do it?"
The Project document deals with personnel, financial and authority issues. It should identify all of the people and departments involved in the project, who will pay for the effort, who can kill the project, who resolves conflicts, etc. It is very tempting to cut corners and let everyone run with their own assumption as to who has what authority and responsibility or by leaving the hard details concerning time and costs until later. This is a mistake; you need to unearth the hidden assumptions of the customer, the engineers, the project leader, etc.
Time and cost estimates are difficult at best and impossible if the project leader hasn't done a similar job with the same organization before. There are no exceptions to this rule. No new project leader can ever give a good estimate, and thus good estimates depend on retaining experienced project leaders. When it comes to being on time and under budget, project leader turnover is the enemy.
THE BUDGET DOCUMENT answers the question "How much will it cost?"
Lack of a firm agreement on budgets has destroyed many projects. Consider the folly of allowing an engineer to spent thousands of hours on a project without any real control over how those hours are spent, then making him or her jump through hoops in order to buy something that costs far less than a wasted day would cost. In general, if you trust someone enough to allow them to design your product, you should approve any purchase request that is smaller than a day's wages (plus overhead) without question. You should also assign a clerk to process whatever paperwork is involved. The concept of a budget is important here. Decide on an amount that each engineer can spend on the project, then let the engineer manage his own budget. Don't fall into the trap of closely managing dollars and hours just because they are easy to measure; manage progress towards a completed product instead.
THE REQUIREMENTS DOCUMENT answers the question "How do we define 'Done'?"
As Frederick P. Brooks said in his book The Mythical Man-Month, "The sooner you start, the longer it takes." We are slowing ourselves down by hurrying too much at the beginning - any small amount of time saved by skimping on organization, architecture, and planning is swallowed up when we spend an inordinate amount of time killing rats and snakes and putting out fires.
Design quality is based on communicating through a Requirements Document. Quality is not merely the removal of all software bugs, wiring errors, etc. Quality is agreement between the Requirements Document and product function as verified by independent testing using agreed-upon Acceptance Test Procedures. The Requirements Document is the basis for solving the problem of determining and documenting what the customer really wants and what the customer really needs (they are often not the same). The Requirements Document is also the key to design quality. It contains the information that makes it possible to build a quality product. The alternative is to implement first, then design later, which is a proven recipe for disaster.
The Requirements Document is the key to dealing with requirement changes as they happen. At first, it is allowed to mutate and evolve. After a specific freeze date, it becomes necessary to refuse to make changes. Treating any further changes as revisions to be made to a delivered product is faster, less expensive, and results in higher quality product than trying to work them into a half-designed product.
The Requirements Document is a representation of what the customer wants, and we all know how difficult it is to discover what the customer wants and then get agreement. There is a classic engineering joke on this:
"How do you tell a real customer?"
"A real customer always knows what he wants until you deliver it, and then says 'I know that's what I told you, but it's not what I want!'"
This is caused by the customer not keeping his end of the development bargain. The only reasonable way to handle this sort of thing is to declare the unwanted first product to be revision A, complete the project ("Complete" meaning that the Acceptance Test results match the Requirements Document), then treat revision B as a new project that reuses many parts of revision A. To do otherwise is to sink into the quicksand of shifting requirements and unclear goals.
How is the Requirements Document developed? In order to understand what you are making, you must identify, develop, and encapsulate the customer's desires in a written document. This should be plain English, structured so that it leads to separable parts based on functionality. The actual Requirements Document starts with identifying each major function that the system must perform. This needs to be a joint effort with the customer. Functions tell what is to be done, not how to do it. Telling the difference between when you have a separate function or just a subset of an existing function takes teamwork, practice, and good communications skills.
Building the Requirements Document should be done as a team, not by a single person. Too often the manager dictates the requirements to skeptical engineers, the engineers can't get essential items into the document, the non-required items get implemented anyway, and everyone does what he or she thinks is needed in an uncoordinated fashion. Meanwhile, the Requirements Document becomes outdated and becomes shelfware, sitting around collecting dust. The end result is a lack of teamwork and a project that is in deep trouble.
It is important to avoid getting into specifications too soon. Learn the difference between requirement and specification - it is vital that the Requirements Document deals only with what, not how. Separating requirements from specifications is a major step to a clean design. A clean design is the foundation needed for predictable system behavior and easy revisions.
THE SPECIFICATIONS DOCUMENT answers the question "What have we agreed to build?"
The Specifications Document tells you how the desired system behaves and what it does. It is important to avoid details until the appropriate stage. This idea, called Late Specification, is similar to concept of late binding in computer programming. It is important to focus on What Must Be Done for as long as possible before detailing How It Is To Be Done. The reason for this is to maintain design and implementation flexibility. Early specification is like premature software optimization; both are a waste of time and both lead to dead ends and bad designs. At the requirements stage, the design work has not started, and specifying details that limit design options must be avoided at all costs.
There is one allowable exception to Late Specification; sometimes it is necessary to prototype small parts of the hardware or software to insure that the design is feasible. This is known as "Top down design, bottom up implementation," and works well as long as you don't skip "Top down" part.
Please note that late specification has the following observable attributes:
 It is very, very effective. Study after study has confirmed that this method reduces the time and cost of a project while improving quality and maintainability.
 It goes against human nature as usually found in engineers and engineering managers. Common sense says to start on the details now. In this case, common sense is wrong.
One common error is waiting to develop the Specifications Document until after the parts are machined, the wires are soldered, and the code is written. This is a major cause of project problems. If you wait that long, you might as well not write the Specifications Document at all. These documents exist to help us complete a project; delaying them deprives you of this much-needed help.
The project team uses the Specifications Document as the authoritative source of information for design and implementation, help files, manuals and training materials. Quality Assurance uses the Specifications Document as the source for developing tests.
The process of developing tests and documentation that lead to questions and clarifications of the Specifications Document is crucial to getting the project done right the first time. Because each group has different objectives, they will read the Specifications Document and discover unique sets of issues to be clarified. Clarifying those issues and sharing the answers as early in the design process as possible is the key to getting the design right. The Specifications Document is what makes all of the people working on the project into a true team instead of separate islands of uncoordinated effort. This is no place for a tyrant or someone who hides information.
THE DESIGN AND IMPLEMENTATION DOCUMENTS answer the question "What do we know right now."
The Design Document and Implementation Document are the short-term memory of the project. They are the informal notes, drawings, and ideas that each project member creates as they work. There should be no set structure and no constraints, with one exception; these notes must be signed, dated, and stored for possible future reference. These are not a tool for project members to communicate with each other, but rather are a tool for each project member to communicate with his or her future self. Common implementations of these documents are laboratory notebooks, notes on a PDA such as a Palm Pilot, boxes full of handwritten notes, and scanned documents dumped to a recordable CD. Such details are best left to the person doing the work - the important thing is that it is possible to go back and read the notes later.
THE ACCEPTANCE TEST DOCUMENT answers the question "Does the product meet the requirements?"
Every part of the project should be tested as early as possible. The mechanical parts should be measured and compared to the prints, the electronics should be tested as subsystems, and the software should be tested as modules. As the testing progresses, a log should be kept of each test and the test results. The logs will become part of the Implementation Document.
The tests should be designed and documented before the actual tests are done. This separation of test development from test execution provides more thorough test coverage and a more objective evaluation. Shipment should be based on passing all tests with no significant problems unresolved.
THE REVISION HISTORY DOCUMENT answers the question "What has changed?"
As revisions are made, you should document what was done, who did it, and why it was done. It is unreasonable to keep updating all of the original documentation and attempting to replace any copies that have already been distributed every time a change is made.
The problem you face in writing all of these documents is that they don't seem to have an obvious payoff. It is easy produce some sort of minimum-effort documentation that ignores the issues that will kill the project. Everyone involved need to decide whether to be part of a professional engineering organization or part of a garage shop - trying to be half of each is much worse than being either.
Requirements and specifications are the foundation of your design, and are the critical first step in creating a reliable, long-lived application. Any information that is missing or incomplete when the requirements phase ends and the implementation phase begins will have a huge impact on the cost and success of the whole project. Studies have confirmed the most expensive errors to fix are those that are missing or wrong in the specifications.
A good documentation scheme will not result in an elegant design without good judgment on the part of the designers, but it will greatly reduce the effort needed to build the system (so much so that the savings dwarf the additional time spent on requirements) and will reduce the amount of disorder. An elegant Specifications Document will increase this effect. If the Specifications Document is used to guide any enhancements, it will minimize the increase of entropy caused by those changes. The benefits of all this work will be easier and faster programming and hardware design, fewer bugs and a longer system lifetime.