I would bet that many of you are scratching your heads thinking "design review(?), what the heck is this DocuDoctor guy talking about now". Or, better yet, "our customer doesn't require us to do it, so we ain't gonna do it!". As our attitudes and dress codes become more casual, so at times can our interest in our customer's needs. We must always remember that it is for the grace of our customer, that we exist. So, now let's look at one little way of keeping our customer happy, involved, and coming back for more: "The Design Review". Let him know that the success of the design is your PRIMARY concern.

For those of you unfamiliar with the design review or DR, it is just what the name implies: a review of the design. Design in this context can be the design of a software application, an electronic device, a mechanical system, or a technical document. Generally speaking, anything being developed from a set of requirements that must be designed prior to its implementation would benefit from the design review process.

If you have first hand experience with design reviews, you have probably conducted preliminary (PDR) and critical (CDR) design reviews before you started building a system. And you already know that the DR process is typically a gathering of informed individuals in a conference room (with a whiteboard, preferably) whose purpose is to review and discuss the current state of the project's design. By the way, the objective of the DR is to improve the product by making it more valuable to your customer.

It is a good idea to carefully design your design review. Developing tools like a check list of design items to be covered will help your customers fully understand the design and provide them with every opportunity to give you feedback. Make sure your customers leave the conference room with a feeling that their time has been well spent and their comments were honestly appreciated.

Our approach to this newsletter is to run through some of the benefits of conducting a DR and then describing what the DR should (and should not) be. And since we are the technical documentation experts, we'll also point out how the project's documentation gets covered during the design review. And while there may be many different ideas on the purpose of the DR, the principles are the same: Present the design to your audience and solicit feedback, feedback, and more feedback!

The people you invite from the customer's team (and your team) are very important to the success of the DR. They should be "experts" in the areas that you're presenting. They're doing you a big favor by sharing their knowledge, thus you should make them and their comments feel welcome.

WHAT A DESIGN REVIEW SHOULD BE

One of the most important considerations in developing and presenting a design review is to present the design in a clear, concise, and methodical way. You want your customer to understand every little detail about the design such that he can tell you what he likes and dislikes. Remember the ultimate objective of this whole process is to avoid a redesign of your system (or documents) down the road. If your customer understands ALL of your details, he can't call you six months later and say: "Your system doesn't meet our needs, change it!".

The tone that you set at the beginning of the DR is very important. You want all of your attendees to know that you actually want their criticism, comments, and praises. By asking for suggestions through the DR, you create a compendium of ideas that will help you and the design achieve the most success and customer satisfaction. All you have to do is to logically step through the design, periodically stopping to ask if anyone has anything to add or comment. It is very important that you not wait until the end of the DR as many questions or ideas will be forgotten. Also, remember to always keep the audience informed as to the basis or reasoning for the design decisions. You may wish to consider using comment cards to help facilitate your customer's feedback. Your audience can use these cards to record their concerns in their own words. The last thing you want is to have five different views on what your customers "really meant". All issues documented on the comment cards should be addressed as soon as possible following the DR to keep the ideas and suggestions flowing. Remember to ask everyone to identify themselves on their comment cards. Addresses, phone numbers, and e-mail address should be provided.

WHAT A DESIGN REVIEW SHOULD NOT BE

I suppose it would be safe to say that most of the attendees at your DR will be familiar with the topic, so there probably won't be any reason to begin your presentation with a lecture on basic thermodynamics or coding standards. In other words, stick to the objectives and outline of the design presentation. Give just enough technical information to explain your decisions and avoid giving so much background that phrases like "big bang" or "primordial soup" crop up in your presentation.

Design reviews should not be viewed as opportunities for you to flex your technical muscles. Remember that the design review is not a test. Your audience is not there to see how well you know your subject. (Although they will notice if you don't know it.) If you have an ego, the day of the DR is the time to leave it home. There are a few statements that should NEVER be said at a DR as some of your attendees will feel as if their suggestions are not welcome:

1) "I guess I'm at your mercy."
2) "Be gentle with your criticism."
3) "Now's the time to get me back for what I did to you."

These "innocent" remarks will convey the idea that anyone finding flaws with "my" design will cause me pain or embarrassment. Be very careful not to cut off the pipeline of information that your job so desperately needs.

TECHNICAL DOCUMENTATION AND THE DESIGN REVIEW

If you are the group's technical writer, your role in the design review may be two-fold. First, you will probably be asked to pull together all of the technical information into a presentation. The important considerations here are that the presentation corresponds with the speaker's words and that the slides logically follow the design's chronology of development.

Your other role in the DR may be to present the "design" of the project's technical documents that are now in outline or preliminary form. What we mean by this is to describe each document's planned approach, organization, content, and level of detail. You want the audience to know exactly what technical information will be contained in each document and how it will support the system being designed. Since we'll assume that you are going to present your documents to the DR audience, let's discuss how this can be done.

There are two approaches to presenting your documentation plans at the design review. The first is to wait until the very end of the DR and discuss each of the documents and their respective outlines. The other approach is to discuss each document at the conclusion of discussions for each relevant design area. Let's go into these in a little more detail.

Waiting until the end of the DR before you present and discuss all of your planned technical documents is a very viable and often preferred approach. However, for large systems that require many different types of documents, design issues that were discussed hours or days earlier are sometimes forgotten. Small systems that may require only a User's Manual and Quick Reference Guide might be best presented after the DR's finale as the customer has "viewed" the entire system. IMPORTANT: Be careful that the documentation segment of your DR doesn't get "axed" because you have simply run out of time. Stick to your agenda!

If you are developing a large system with many types of complex documents, you may wish to discuss each design area followed immediately by how you will document that area. For example, your discussion about the design of your database would most appropriately be concluded by a discussion of the contents of the design document as it relates to the database. The customers will provide you their best insights as to what they would like to have included or excluded in their documents while they are focused on the subject matter. Similarly, your configuration management documents should get presented following your quality control discussion and your maintenance documents should be discussed following your presentation on system reparability, and so on. NOTE: If your employer or customer requires you to follow any document specifications or other prescribed formats, you must "design" your document within those guidelines.

All in all, the design review is not for everyone nor for the thin-skinned. If you've been conducting design reviews for most of your professional career, then these ideas may help you refine your processes. If you've never been through the design review process with your customers or peers, then you may seriously want to consider it. The level of detail and degree of formality can be adjusted to fit nearly any project or situation and still be useful and worthwhile. Just remember that communication between the players is paramount in making any technical project succeed the first time through. The DocuDoctor would much prefer to see your documents be healthy and happy through an ounce of prevention instead of seeing them arrive by ambulance at the "DocuHospital".

The next newsletter in this series will be "Adding Value with Graphics". Upcoming titles and previous issues in the series "How to Save A Quarter Million On Your Documentation Tasks" may be found on The DocuDoctor's page of MSD's web site.