What's the Big Deal? Reference Architectures.

If there is one thing guaranteed to stir up a bunch of architects into a frenzy, it's a discussion about reference architectures.  Which is kinda sad, really because they're rather dry documents.  However, they do have a big impact on folks like me.  As a vendor architect, it's really the reference architect that forms the basis of every conversation I have with a customer.  When I was a customer architect, the reference architecture documents where the only vendor materials I ever read.

I'm currently working on a big reference architecture program so I've been pondering the nature of reference architectures a bit.  I thought I share some of those ponderences here.  If you couldn't care less about reference architecture, feel free to stop reading here.  No rainbows or ponies in this post.

If you've never been the author of a reference architecture document, let me share a little secret with you:  They all suck.

What?  How could this be?

It's the nature of the beast, I'm afraid.

Here's the deal.  Our friends in engineering spend huge amounts of time creating really cool products that do all kinds of things.  They then spend a huge amount of time documenting all the various permutations of what that software can do.  With enterprise class software, this list can get pretty extensive.  Thus are reference architectures born.  Instead of focusing on all the great stuff that you CAN do, it says, this is the short list of stuff you SHOULD DO.

Naturally, the best reference architectures are very specific.  The word we use in our business is "Prescriptive Architecture."  Good reference architectures are PRESCRIPTIVE by telling folks DO THIS and DON'T DO THIS.  The problem is that the products in question always have tons of great features that can be implemented in all kinds of cool ways.  This implies options.  But we just said that good reference architectures are prescriptive.  This implies few or no choices.  This is the rub.  There is a constant tension between generality and specificity.  You never get this right, it's a constant source of friction.

The other thing that happens is that reference architectures are almost always written by a large group.  After all, if the system is simple enough to be well understood by just one person, you probably don't need to write a reference architecture in the first place.  Right?   I'm sure you have heard the joke that a camel is a horse designed by committee?  Yeah, same principle here.

So, reference architectures suck.  Then why do them?  Because not having them sucks even more.  Without a reference architecture, you have no benchmark to shoot for.  There is no "standard" in your deployments.  This means that there is no direction to customers or partners and they go off in all kinds of tangents.  Not good for anybody.  I firmly believe that reference architectures are a necessary evil in any complex system.  The more complex the system, the more need for reference architecture.

This, naturally, takes me back to private cloud.  As I have written here in the past, Private Cloud is probably one of the most complex solution spaces I have ever been involved in.  OK, apart from running a Nuclear Power Plant, but I wasn't designing the thing, I just worked there.  Of the things I've actually designed myself, this is the most complex by far.  Hence, I'm working on a reference architecture.....

If I'm going to design something, I need to have a set of design guides.  What are my goals in this system?  How do I know that the work product is successful?  Who is my audience? etc..  Let's think about this in the context of reference architectures.  In my case, I work for a technology vendor, so my audience is pretty clear.  I need to speak to customer and partner architects.  These are people who may be or may not be familiar with my product who want to implement a private cloud on our platform.  Luckily, this is a pretty small audience and I know this audience well.  It is almost impossible to write a good document without knowing your audience.

Rules for writing a good reference architecture:

1. Know your audience.  Who are you writing for and what do they need to get from the document?  What are their key pain points and how do you alleviate those pain points.
2. Know the current state of the art.  There is no point in repeating information that everyone already knows.  If something is a widely accepted norm, just say so and move on.  Nothing worse that page after page of explanation of something everyone knows already.
3. Present the architecture sequentially.  Think about the decisions that your audience will make and the order they will need to make them.  There is no point in telling them how to operate the system before we talk about how the system is built.
4. Minimize decision points.  The fewer decision points that the customer needs to make, the better.  Yes, you will need to allow customization of your design; yes, you will need to have the customer make design decisions.  However, the point is to be PRESCRIPTIVE which means reducing choice.  They can always pick and choose from your guidance if they disagree but too many variables make the reference design useless.
5. Be concise.  We architects love to hear ourselves talk.  Resist pontification.  Just lay out your guidance as concisely as possible.
6. Do not generalize.  Saying things like "backups are good" and "No single point of failure" are pretty much mom and apple pie.   Nobody doubts them.  The question is HOW your design enables things like this.  Be specific.  No need to convince people that these things are good or necessary. 
7. Think in layers.  The reality is that your system will look different to different people.  You may need to produce an operations guide, a deployment guide and a architecture guide separately.  That's OK.  Better to be focused on one audience at a time.  While you're at it, don't forget that architecture is about aligning the business problem to the technology.  If your architecture doesn't discuss the business problem or how the end customer benefits, you're probably missing something.

I'm sure you can think of others.  Hopefully, we can all follow these rules and suck less.  Don't be shy in letting me know what you think!!