I've been involved in a few Agile projects and have formed a few opinions some positive and some negative. For example, I don't think that Agile methods work very well for established mass market desktop products while I think it works superbly for IT projects, web applications and projects that have a relatively small number of customers. I especially like the ability to come to a stopping point quickly and show the changes to the team and customers, which is what I'm going to talk about today.

I love weekly or bi-weekly demonstrations with the team and monthly customer meetings because I can get feedback and adjust my product rather than committing to something very uncertain. This demonstration schedule does not necessarily match the iteration cycle either and can run on just a developer's desktop. The point is to show the latest changes from one demo to the next, give credit where it is due, make minor adjustments to design and requirements and give a clear indication of the velocity of progress. My favorite benefit is the amount of sleep I get at night.

Yes, sleep is my favorite benefit. I don't worry about whether the customer is going to like what I am building by the time I hit delivery date. I don't have to worry about the work-flow because the team and product management have tried it a dozen or more times. I don't have to worry about major silly bugs because the demonstrations have usually exposed them already. As we know, all software crashes at the most embarrassing time: during a demo in front of a crowd. By ship date I can rest assured that anything glaring, bug or requirement, has been discovered and solved.

Building demonstrable code is not easy on a one or two week schedule. The goal is to stop building new functionality early enough to integrate and stabilize the code for demo. I like having only one week between demonstrations because the code base has not moved terribly far forward, which makes integration easy. I usually spend a portion of the day prior just for testing the changes and making fit and finish modifications. However, I can't do very much in the way of major changes. I work to get to the next demo and so I either must finish my changes entirely, disable the new code or demo around the incomplete code. Planning the demo is obviously important.

It often happens that the conceptualization of a work-flow turns out to be somewhat flawed. One can argue during the design phase that the flow is wrong but it is difficult to dissuade some individuals without having them actually try it. A demo illustrates the work-flow issues with perfect clarity. The results are the requirements, UI, back-end and test plans may change, but they changed early enough in the development cycle to be corrected investing a major development effort.

Regular customer demonstrations may not be an option. Some customers find demos annoying while others are happy to see progress. Regardless, showing them the progress made and the work flow at regular intervals is incredibly valuable in ensuring that the delivered product is what they want. The changes can be as simple as labeling issues where the customer realizes that the label is Ok, but they really call it X or Y. Its a 2 minute fix that makes the customer happy. Other changes can be very invasive, but you caught it early so there is hopefully time to solve it.

Making weekly team demonstrations effective is a straightforward process. First, have goals for what should be accomplished from one week to the next. Second, plan when to stop development and focus on integrating, testing and bug fixing. Third, during the demo describe the changes from the previous demo, giving credit where it is due. Fourth, modify the code after the demo to include suggestions and comments.

The weekly demo is incredibly valuable for finding flaws in requirements, work flow and implementation. In the best case, it validates that you were right all along. In the worst cases, it gives you the opportunity to change directions earlier rather than shortly before a delivery date. In any event, you know that by the time you deliver the final product that you are aligned with customer expectations.

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.