I.T. Archeology: Why You Need an Architecture Repository

If you've managed any part of a thriving information technology ecosystem, you've doubtless gotten that call at about 3 am (why is it always 3 am?) by someone with news that a system you hardly ever think about has suddenly failed.  The new person in charge of the application has no clue what's wrong or how the application works because the previous owner left without performing any knowledge transfer.  Worse, there doesn't appear to be any documentation.  Nobody really knows how the system is put together.   You and your team will now spend at least a day (maybe several) trying to troubleshoot the problem - and learning exactly how the system works.  If you've ever faced a problem like this…you obviously don't have an architecture repository.  If you did, the new person could have dived into that invaluable resource, quickly determined all of the critical components and maybe immediately figured out what the problem was.  In a world where the average tenure of an I.T. professional is 2-3 years - you can't afford to leave key business application details to "tribal knowledge" or "it's all in Bob's head".  You need an architecture repository or you'll be like an archeologist trying to piece together the history of a long-lost civilization.

 What Is an Architecture Repository?

To summarize The Open Group's view on the subject in their TOGAF framework, it's a managed storehouse that houses and organizes all architecture information.  Including models, diagrams, documentation, etc. created during the development and implementation of a system.  Its purpose is to serve as a central location for knowledge capture and reuse.  It's the ultimate reference for the composition of a given system or solution that tells you everything you need to know to implement, manage, maintain, support and troubleshoot a system.  It requires additional time up front when you are building and designing a system, but it will save you hours when something goes bump in the night.  It's especially nice to have this type of information when the CIO and COO are standing in your office scowling at you, tapping their feet and asking "what's the status?" every 5 minutes.

 So, what's included in a good architecture repository?  There are a few items that absolutely must exist in any architecture repository:

• Taxonomy:  TOGAF (I do love me some TOGAF) refers to this as the "Architecture Metamodel" and "Reference Library".  All it really means is that you should have a blueprint or formal definition of how you will organize and manage the different elements within the repository.  It defines the structure, the relationships, and standards (e.g. templates, design patterns, approved technology standards/approaches) in order to ensure your repository is consistent and coherent.  Basically, if you can't find anything and what you do find doesn't have the information you need - your repository is worthless.
• Architectural Assets:  Assuming you've developed a good taxonomy, it's time to fill it.  These architectural assets will provide a holistic view of the organization as well as provide critical detailed/specialized viewpoints into how the plumbing of your organization works.  TOGAF calls this the "Architecture Landscape" and it consists of all your architectural artifacts - including how they relate to one another.  These assets should include things like:

1. High-Level Organizational Architecture:  TOGAF calls this your "Capability Landscape".  What are the business capabilities your organization leverages to achieve its business goals and strategies.  What systems, solutions and processes enable these capabilities.  What data supports these systems, solutions and processes.
2. Solution and Technical Architecture:  TOGAF refers to this as the "Solutions Landscape".  It's the architectures that are specifically focused on the individual business units and the specific solutions that support them.  This is where your details lie.  At the bare minimum, you should have a "current state" or "as-is" set of documentation for every system and critical function.  As your practice matures, you can add in "target state" or "to-be" architectures to the mix to show a roadmap of how your technology will be evolving.  But it is most important to make sure that you have current state mapped out for when you get those 3am calls.

• Governance Repository:  If you read my scintillating (not!) account of why you need an Architecture Review Board, this is the area where you would record all of the governance activity that the ARB undertakes.  While this may not be immediately important when it's 3 am and the world is ending, it can be extremely helpful when trying to determine why a particular design decision was made or why an exception was granted for a specific solution and can give further insight into why things are the way they are. 

 In general, this is the bare minimum that any architecture repository should be built from - and will likely be the most useful things to focus on early in your Enterprise Architecture journey.  There are some additional things that the TOGAF framework mentions that can be useful such as an Architecture Requirements Repository (this is especially useful for heavily regulated industries) that lays out a set of standard requirements that all systems must meet.  But generally speaking, when trying to get your fat out of the fire, the above items will give you the most value.

 If there are additional topics you'd like me to opine on or if you have questions, just leave those in the comments.  I do read them all, even if I don't reply to all of them.  Happy Architecting!