There is huge value in design reviews and they are almost always worth sitting through. I say almost always because just about everyone has sat through a review where the designer didn’t understand the problem at all and the next hour or more was spent educating. The value in a good design review is that the design is validated, people understand what is involved and can start working on implementing and testing the design. The review is also an opportunity to further refine a design that results in a better, collaborative solution. All of the above is valuable in one way or another.

The makeup of attendees at a review varies, but it often includes project management, QA, developers and architects. This range is why various diagrams become crucial. QA and project management can come from very different backgrounds and thought processes than those of engineers that leads to some interesting communication barriers. Text can often be interpreted in more than one way, and consequently other engineers can miss the point entirely too.

Some QA people are junior engineers working their way into a traditional role as a software engineer by getting a job where the barrier to entry is lower. Others used to work in as an insurance customer service rep and have really good analytical minds. My favorite QA person used to be a Cobol developer and has her own scientific method for finding bugs in a user interface.

Project managers are a disturbing mix of anyone who manages a project. I have had C and VP level people managing projects and pet features as well as a former editor for a publishing house. They can be brilliant orchestrators of people and technology, equally adept at installing the latest Linux flavor, configuring their Blackberry for a new email server and scheduling the next three weeks of your life. Others found their way into project management as they switched from one career to another and may have good management skills and are completely inept when using anything but the simplest features in Word, Excel and Outlook.

Diagrams are a critical component for a design because the variety of people and learning styles require that you provide more than method for conveying information. There are several kinds of diagrams, but two usually drive home the point for any audience. The first is the structural diagram. These are the UML class diagrams and Entity-Relationship models. Engineers love them because a reviewer can figure out from the interfaces what she is supposed to do.

The second diagram type describe process flow and logic. UML activity diagrams and flow charts describe the processes in the order they would execute within the system. These diagrams resonate with non-developer staff. They also help with a another class of reviewer: the schmuck that doesn’t read the specification before the meeting.

Non-developer types don’t care about structural diagrams except when it is an API you will hand to external users. Does a QA person care if you are applying a “Chain of Responsibility” pattern? Likewise, UML Sequence diagrams describing method calls are equally unhelpful to non-developers. The project manager may care if you are following a well-defined design pattern and have a solid structure. It depends on the person and their background. Some CTO’s are technology visionaries that have no real development skills while others are skilled former engineers. Show these people the structure of code and you may get a good response and then again, you may not. Show them how it will execute and how users will experience and you will have told these reviewers something they can act on and contribute to.

ER models are a special case of structural diagrams as they are sometimes necessary for QA to do their job. QA has a wide range of responsibilities and skills. Sometimes they check whether the thing stored through the UI is what was actually stored at the back-end by executing SQL queries. They really need to understand these relationships and an ER diagram is the best way to do it. Applications that have an ETL type process usually have database savvy QA staff.

Nearly every design describes some kind of process and that’s where the flow chart comes in. Now I know just about everyone knows what a flow chart is and the last statement generates a big “duh.” And yet there are a lot of low level sequence diagrams. The flow chart is great at explaining the big picture. Want to explain the logic behind an ETL process? Need to show how your JMS publisher-subscriber dispatcher determines what should get an event? Maybe you want to explain how you write a blog. Here’s how I do it:

This chart clearly shows the entire process from start to end. A sequence diagram may do the same thing, but gets into specific method calls and goes far too deep for most people to understand what the system is trying to accomplish. Personally, I prefer sequence diagrams for explaining a specific process thats already implemented or the details behind an API call.

Back to the diagram; one could easily write a paragraph on each process. In fact, I would argue that you draw the diagram first and then use it as an outline for your document. I should be able to describe my entire blogging process, up to “Publishing Process”, in eleven paragraphs or less. I may write much more than that if I try to write first and then develop the diagram.

I’ve noted some resistance to creating flow charts. The causes are often that the designer doesn’t have a tool to diagram with, its too time consuming or they don’t know the iconography and worries that he will look foolish.

The first cause is very common. Visio is the most common tool but it isn’t included with Office. It can be accomplished in Powerpoint too, but it is very time consuming. I use OmniGraffle for the Mac and think the results are pretty good. UML modeling tools do come with some IDEs now but may not support the activity diagram. I have tried a web site called Gliffy. It’s good in a pinch and cheap to sign up for (free and premium versions), but I still prefer desktop tools at this time.

The second cause drives me batty. Diagramming anything is time consuming. It requires patience and attention to detail. Failing to diagram usually means that your review will be longer, sometimes by hours. The reviewers will sit through that meeting and have their time wasted too. A flow chart would have shown them quickly that your vision of the process is incorrect and they could have quickly alerted you and the meeting could be shorter or rescheduled entirely.

I mentioned earlier that a flow chart can become the outline to your design. You could type a lot of text for hours or you could make a really good diagram and quickly document it. You may spend less time doing the latter method and your reviewers may read through more of your document.

The third cause is surprisingly common and understandable. Picking the wrong symbol or labeling it incorrectly can be embarrassing and may derail what could be a good review. No one wants to look like a fool and they want to be told they are a fool even less. Having one of your designs reviewed is incredibly stressful except to the overconfident. Every novel idea is scrutinized and a target of comment, embarrassment and even ridicule. A review is supposed to be about collaboration, refinement and building something brilliant as a team. It is reasonable for someone to try limiting their exposure by avoiding certain diagrams.

I found that the Internet has plenty of flow charting tutorials, which should help the worried designer. I also found that some tutorials conflict! Take a look at these:

These five examples are similar. They agree on several symbols and their meaning, but not all. Many have the symbols for punch cards, paper and magnetic tape too. Most people don’t use these technologies anymore, however, do a search for “paper tape reader” and you will still find companies producing paper tape readers but I digress.

Above are four symbols they all agree on and will get you through 99% of common process descriptions. You can use them pretty safely and get your point across. Only in a few environments is there reason worry about the iconography and its proper use. I would take care in medical, aerospace and military designs that the iconography is correct by referencing other accepted designs. Small, medium and large businesses outside of those spaces are pretty safe. Your only worry is that guy that brings up spelling or grammar mistakes during a review, he’s bound to have an opinion on the iconography too.

These picky people are great for reviewing designs, but not during meetings. Keeping a design review on track is difficult because of all the interesting technical aspects that other reviews want to explore. Spelling mistakes can be forwarded in an email before or after the meeting. This gives more expensive meeting time to the technical issues. I often send my documents out to these people as early as possible and get their feedback before the meeting. Their spelling and grammar checking actually shows they are reading the document carefully. They have technical opinions too and they want to help, just manage their feedback so it comes out in the best light.

I’ve mentioned a lot of reasons to use flow charts in designs and they appear to be about shortening the design review. My goal is not to shorten a design review at all. Lots of interesting things can be learned from your peers. The goal of diagrams is to quickly describe the structure, process and use of the component you are building so that you can efficiently justify your design, find its flaws, get ideas from other people and to educate those that will be implementing and testing the code. Design reviews can get everyone on board quickly but that can only be accomplished if your team understands both the structure and the processes. So dust off the old flow chart and remember that if you have a class or ER diagram then you probably need a flow chart too.