Let me paint a picture . . . .

In the Sept. 24 Computerworld there was a delightful opinion piece ("Opinion: Five Diagrams Beat a 'Victorian Novel' ") on the use of diagrams and flow charts in presenting system designs.  I'd like to go further than Michael Hugos went.  Back in my early days we were taught to prepare flow charts and system diagrams for everything we touched.  That sort of went out of style in the 90s, as companies started to move towards 'enterprise' applications that were developed by large software houses. 

Things are changing again.  SaaS is pushing application developers into building modular packages that can be easily installed and managed remotely by teams in multiple locations.  Support teams can be assembled from remote locations around the globe to support a particular application or even a component of an application.  The key to getting these teams together, and communicating, is the adherence to standards and strong documentation.  I find the best place to start any discussion is with a good platform diagram that shows the servers, network appliances, vlans, storage devices, etc. 

In a crisis situation, when someone needs to take a look at a problem, they don't have time to read through a document explaining how things work; they'll be in a hurry.  They need to be able to see the big picture and, quickly, begin to focus on the specific issue.  A good picture is worth a thousand words.

While these diagrams need to give an engineer enough to understand the scope of the environment, you really don't want to crowd too much in the way of notation onto them.  A document can be linked to portions of the drawing so that an engineer can go right to the material from the drawing.  The diagrams need to capture the basic structure of the platform, enough to identify what pieces are where and how they communicate.  There still is a need for the narrative; I don't advocate putting too much detail on the page as it can become confusing in a hurry.

And, while I'm at it, let's talk about using more diagrams in our written material, as well.  I find it hard, sometimes, to follow procedures when the instructions are presented as a series of paragraphs.  Give me a simple flowchart that shows the basic steps involved.  Quite frankly, some of the driest reading I have to put up with comes from IT people.  For a group of people that whine about documentation, we seem to write some fairly verbose material.

I also find it very useful when trying to get a concept across, to use electronic whiteboards.  While describing the widgit, I can draw the widgit and let other participants manipulate it as well. 

So, get out those crayons!