Using the Enterprise Architecture Toolkit (EATK) to Capture Architecture Descriptions

I created tthe Enterprise Architecture Toolkit (EATK) to make Microsoft Word 2007 a first class citizen in the architecture description area. As I described in  my recent post called "Does Office Tools Still Play a Role in Architecture Design?" I talked in length how at least for the time being we are still using productivity tools for describing our architectures. Since this is the case more often than not, the EATK uses Word to articulate these architectures.

In this post I will give you a brief summary of how the EATK helps with documenting architecture descriptions.

There are a series of problems that the EATK is trying to solve by leveraging Microsoft Word 2007. I will not go into length in all of them but highlight some key areas.

The first is to make the creation of architecture descriptions much more intuitive and easy to do. Even though tools such as Word are easy to use we still see complexity here. That complexity comes in the form of:

1. Duplicate data entry

2. Template overload

3. Limited ability to control quality of descriptions

4. etc.

As shown above, we are adding more and more documents to an already large portfolio of documents that need to be completed. In the past this was manageable but now documents can be bloated and information has a higher probability of being duplicated. Often times this is a result of tightly coupling a document with a process step that results in a great deal of redundancy.

So how does the EATK attempt to solve these challenges? It does so by changing the context in which Word is used. Changing the context is a sometimes not an intuitive task. It takes some investigative work both on the capabilities you want to expose and potential development to the tooling.

The underlining goal is to change the role of Word from simply a word processor to more of a User Interface (UI) for designing architectures. Applying structured UI concepts to Microsoft Word provide many benefits to the architecture document.

1. Structured Content – Information can be better described in the document. The reason we want to do this is because of the challenges mentioned regarding how information doesn’t integrate well with process or future design activities. One example is the process of importing a model into an architecture document. Often times we import a picture that represents a model of a specific view point of an architecture. If we had an information model we could specific that the model imported is indeed the logical model, rather than a generic image file.

2. Extensible – With a little more structure information has meaning and definition. This makes that information extensible to other processes downstream.

3. Consumable – Abilities to consume external content is also possible with a more structured interface. As an example, if you choose to you could import external architecture information from other systems to automate you design efforts.

Let's take a look at this from a technical perspective. Below illustrates how the EATK separates areas of concerns with the implimentation in Microsoft Word.

1. Tool - The mechanism of Microsoft Word is referred to here. The tool provides extensibility into the user interface that provides Office Ribbons to execute tasks easily with a level of context and Office Task Panes that extend the UI with additional entry or listings of information.

2. Document - The document provides the way in which a user can enter in architecture descriptions. This is different in the EATK as the document acts as the glue between the Tool and the information itself. This is accomplished through a architecture document template and the use of word custom controls.

3. Information - The information in the document is managed completely different than in a traditional document. All information typed into the document is linked back to an XML node behind the scenes. This fully qualifies what is typed the information. Not only is the information rich but it is extensible.

Let's take a look at the implementation in the EATK. Below you can see how Ribbons, Meta-Data Properties and Task Panes are implemented. The EA Toolkit Ribbon shows at the top of the screen. These represent the functionality the functionality in this tool.

The meta-data properties provide context around the document or high-level architecture itself. There are the following fields: Title, SDLC Phase, Architecture ID, Architecture name, Project ID. This information is utilized in throughout the implementation from integration to the workflow to surfacing information in context.

Task panes shown below are able to make architecture information as transparent as possible. It allows the EATK to surface information from the architecture meta-data repository. With a double click on a pattern or asset that information is populated in the document. The document tracks if an existing pattern is used so the governance process can track reuse (among a series of other benefits).

The new OOXML features in Office 2007 allows us to separate the information from the document in a much cleaner way. With the new formats, the entire document is XML based. The document itself is a zip compressed file with the extension of .docx. In these files are a series of file folders.

The customXML folder is used in the EATK. Below we see that item1.xml is the system architecture XML file used for storing architecture information. All information entered into the System Architecture Document will be stored here.

Additional Screen Shots