If you can’t describe a system with simple diagrams the system is flawed. I’ve seen diagrams for cars, military vehicles, computer chips, and other very complex systems. Block and flow diagrams that simplify and explain in just the right amount of detail. Yet, when it comes to software applications, even complex ones, I am finding diagrams difficult to find. To make matters worse, when some systems that were architected in code do have diagrams put to them you find the picture is not so pretty.

One of the best techniques I’ve learned for architecting a system is to start with diagrams.

Start Simple

Diagrams don't need to happen in any special way. Creating block and flow diagrams doesn't mean you need to go out and learn UML (thought you are welcome to if you like). The most basic way of doing them happens to be my favorite. Just break out a pencil and some paper.

If you do design on paper and have to share with others who can’t just read your paper notes is when a program needs to come into play. And, there are a lot of programs available to generate diagrams with.

Two Types To Start With

There are two essential types of diagrams to architect or describe a system.

• Block Diagram - Basically, describing the different subsystems, components, objects, or modules and how they interface or interact with each other. What goes in, what comes out, and how they all connect together.
• Flow Chart - How do users or data flow throw the system? What happens at decision points? The flow from one end of the application to the other. Or, from one point to another.

Benefits

Coding is fun. Developers and programmers tend to gravitate towards writing code. Architecture and documentation in general is never quite as exciting. That's one of the reasons so many open source projects suffer from documentation voids. It's just not as much fun.

There are some real benefits we can all get from diagrams.

1. Finding those WTF moments in the flow before you code your way into that corner. (this is one of my favorites). This saves time, money, and frustration.
2. Makes it easier to explain. Explaining things is often not easy. Especially when people are located all over the word (as with open source projects) or you are trying to explain something to a client, manager, or user experience expert. Diagrams provide an easy way to break things down to explain.
3. Breaks projects up into build-able chunks. Creating and estimating tasks lists is not an easy task. Diagrams help break up something large into something smaller and more accessible. That in turn makes describing and estimating tasks easier. Diagrams can describe dependencies which help with the ordering of tasks and figuring out what is optional or required.
4. Building for reusability. When you visually see the different components and how they interact with each other it's easier to group reusable parts. Reusable parts mean less code, less debugging, and more building on what works.

Now is the perfect time to start talking about Architecture. As code is transitioned to PHP 5.3, as work on Drupal 8 begins, and as modules start porting to Drupal 7 we can begin to make things cleaner and easier for people to understand.