Drawing Effective Technical Diagrams

By |2010-04-29T09:41:00+00:00April 29th, 2010|Enterprise Architecture|

As architects, we spend a good bit of time trying to get a very complicated set of ideas communicated in a clear, consistent, and understandable manner.  A simple diagram with a clear story can be very compelling.  A poor diagram can actively sink your efforts. 

A great example of a poor diagram appeared on the front page of the New York Times a few days ago.  This horrible diagram attempts to describe the complexity of the US Afghanistan Policy in the war we are fighting there.  The diagram didn’t have a clear message, metaphor, or organizational method that allowed key observations to be drawn from it.  (copied below)

About the only decision that this diagram supports is “simplify this.”  But there is no clear way recommendation on how to do that, the areas that need the focus first, or even the rationale for the complexity that has emerged. 


So what can we do?  We live in a complex space.  We’ve all delivered complex diagrams before.

I got a note from another architect this morning pointing to a masters thesis produced in 2006 by Noah Iliinsky at the University of Washington.  This masters thesis, titled Generation of Complex Diagrams: How to Make Lasagna Instead of Spaghetti , provides a great deal of good information on how to tell if your diagram is any good, and how to develop a better diagram for the audience at hand.

Direct link to PDF: https://digital.lib.washington.edu/xmlui/bitstream/handle/1773/3100/iliinsky_complex_diagrams.pdf?sequence=1

Reference: https://digital.lib.washington.edu/xmlui/handle/1773/3100

It’s a good paper, and worth a look for any architect wanting to learn to improve the kinds of diagrams that they produce, and best guide the decisions that need to be made.

Service Oriented Architecture Conceptual Model

By |2010-04-16T23:49:12+00:00April 16th, 2010|Enterprise Architecture|

Almost two years ago, I described some of the key concepts of service oriented architecture, including the distinction between a canonical model and a canonical message schema.  Since that time, I worked on a wide array of models, including Microsoft IT’s Common Conceptual Model.  That model (CCM for short) is the metamodel for IT concepts in Enterprise Architecture.

I received a note recently about that old post, and how valuable it was to the reader.  It occurred to me that those concepts were part of our Common Conceptual Model, and that a “SOA-Specific View” of the metamodel may prove interesting.  It was. 

I’ve attached the SOA view of our Common Conceptual Model for this post.

SV - SOA Concepts

A quick set of notes on my conceptual models.  

  1. Two terms separated by a slash (Application / Installable Software) are distinct terms for the same concept. 
  2. The associations are all “arrows with verbs”.  Read the associations along the direction of the arrow.  (e.g. “Application Component implements a Shared Service”).  I intentionally avoided using UML notations like “Composition” and “Aggregation” because they are difficult for non-technical people to read.
  3. Many verbs on an arrow – The stakeholders couldn’t agree on which verb best described the relationship, so we used multiple distinct verbs. 
  4. In my prior post, I used the term “Canonical Schema.”  Our stakeholders preferred “Shared Message Data Contract.” 


The key relationships to notice in this model are the ones that may be the least expected ones: the connection between the obvious SOA concepts like “Contract” and “Canonical Entity” and the not-so-obvious SOA concepts, like Business Process and Business Event. 

When SOA is done well, it is part of a seamless ecosystem between the processes that people perform and the systems that support them.  Being able to see the parts of the system and how they connect is key to understanding how to build a truly effective service oriented architecture.

Building less than you know you’ll need

By |2016-09-28T22:47:06+00:00April 9th, 2010|Enterprise Architecture|

In the past, I’ve been guilty of this sin: gold-plating.  Back when I was a solution architect, I would (often) think about the things that the business is going to need, but never asked for.  I would occasionally include elements in the design to support those needs, even though the business didn’t ask for them.  Here’s the sad thing: I considered it to be a good practice.

I was wrong.

Let’s pick a situation that most folks understand: e-commerce.  If you visit an e-commerce site and you buy something, you (the customer) will want to be able to track and cancel that order.  One common additional feature is the ability to track the shipment itself (through UPS, Fedex, or DHL).

You are building a brand new e-commerce system.  Let’s say that the business requirements ask for a set of pages for a shopper to view and cancel their orders.  But there is no requirement for tracking the shipment.

Still, you know that someone will ask for it someday, so you build in some features to allow the shipment to be tracked.  Perhaps you hold on to the tracking company id, the tracking number, a URL for tracking, and some logic to pull it all together.  You even build a generalized “tracking API” so that a REST client can track the shipment in a mashup.  How cool is that!

That would be gold plating.

Is it a sin?  Is this good or bad?  (more…)