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.

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.

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.

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?  Well, occasionally it’s good.  I would suggest that most times, it is bad.  That is because I’m making many assumptions about the future of the software I’m writing. 

I’m assuming:

1. that the software will live long enough to get that requirement.  It is entirely possible that the software I’m writing today will be phased out long before that particular requirement is expressed by the business.  My software may even end up being replaced by a commercial off-the-shelf package, or online service, that has that feature already in it. 
    
2. that I am understanding the requirements correctly.  It is entirely possible that my assumptions about the “right” way to implement the “future feature” are incorrect, and that the cost to fix my guess may very well exceed the cost of fixing the software without my guess.  In other words, I could make things worse, not better, by guessing.
    
3. that my guess is not adding complexity and therefore increasing the cost of ownership unnecessarily.  This is a big one.  The cost of owning a system (managing it, maintaining it, hosting it, recovering from errors, etc) is directly proportional to the complexity of the software.  All those “hooks” for the future can add up.
    
4. that the time I’m spending putting in those hooks is spent in a valuable manner.  Business folks will often find themselves with a long list of features that they want in their software, and when developers hit them with the cost estimates, they will inevitably cut back on some of those features.  If we take time to add in features that they did not ask for, what about the features that they did want?  What of those?  The money we are spending belongs to the business.  The business should have the right to decide how that money is spent. 

In conclusion: It is often far better to write LESS software.  Just say “no” to putting in all the hooks that we believe that the business must want, but has not asked for.