Ship It! - 4.3 Collaborate to Define Interfaces

The teams working on adjacent layers meet, and together they flesh out the interfaces that their layers share. If you know that the client application needs to log in, then you know that a log in call must exist in the web server layer. The teams collaborate and come to an agreement on the method names and signatures. You then code each method but return only canned data. In these meetings, you begin to define how the layers will communicate with each other. Your teams flesh out such details among themselves so that after this meeting (or as many meetings as it takes), everyone involved knows and understands the interface points between each layer. The best architectures aren’t defined by an “architect” in an ivory tower; they are collaborative efforts. Instead of having a guru drive by and drop a completed architecture document in your lap, your team works together, leveraging and increasing everyone’s experience.

Tips:

• Always have a single person lead your meetings. This person always has the floor and must “give permission” before anyone can speak. Having a single person lead the meeting will help prevent the meeting from turning into a shouting match.
• Record notes on a white board throughout the meeting. With the information on a white board, everyone can see what method signatures you’ve agreed on in real time. If you take notes on paper, inevitably someone won’t see what you’ve written.
• Andy Hunt suggests trying using LEGOs or wooden building blocks for the objects in your system. You help the more junior members understand the system and the relationships between the different objects when you give them something tangible to see and touch. Sometimes the intangible nature of our work makes the system components difficult to visualize and understand. Whether you draw objects on the white board or move blocks on the table, have a visual or tactile representation of your system.
• Record the interfaces and publish them. You can use a printed document, a web page, or a wiki, but regardless of what medium you use, you must make the information publicly available. The last place you want to keep secrets is an object’s interface.
• Hold your meetings where you won’t be interrupted. You want to minimize the number of times you have to shift gears and answer questions.

Tip 20: Architect as a group

I'm thinking that a poor man's CASE tool, aka cheap digital camera, is a nice way to document the group's thinking.  I can't picture in my head, however, how I could use blocks to convey a software architecture.  I must do a bit of digging to see what I can find on the topic.