Pragmatic Approach to Describing Solution Architectures

8/2/2019 Pragmatic Approach to Describing Solution Architectures

1/24

Pragmatic Approach to Describing Solution

Architectures

5 out of 5 rated this helpful Rate this topic

Mike Walker

February 2008

Applies to:

Enterprise Architecture

Summary: This article aims to provide guidance on how to solve common challenges with current

architecture documentation by going over a series of add-ins and templates that the Enterprise

Architecture Toolkit (EATK) provides. (30 printed pages)

Contents

Introduction

A Brief History

The Reality of Current Architecture Documentation

Rethinking the Traditional Architecture DocumentOptimizing Office Word to Describe Architectures

The Architecture of the System-Architecture Document

Conclusion

References

Introduction

Since the dawn of information technology (IT), engineers and architects have created reams of

documents to describe their solutions. These have been published in three-ring binders and placed inobscure places on bookshelves, eventually to collect dust and be forgottensomething with which

engineers and architects have had to deal as a fact of life.

As time has passed, documentation has evolved from a listing of detailed methods and procedures to

the separation of multiple aspects of the solution from the detailed APIs and user-interface (UI)

design to the architectural aspects. Integration with developmental and architectural processes

furthered this activity and, eventually, became a required and common practice. By doing so,

governance processes in many ways restricted forward progress. In many ways, governance hascreated both justified and unjustified restrictions to forward-moving progress on designs and coding,

if a set of documentation had not been completed. This has led to frustration and productivity

blockers.

In this article, we will explore how architectures traditionally have been designed and described. By

understanding where we have come from, we then can understand how to improve and changefundamentally how the architectures are described. This article will:

Provide architects with a way to articulate the architectural processes in which architectures

are described.Provide architects with a set of best practices for describing architectures.

Induce new and innovative ways of thinking about a classic problem.

Provide standards that will be helpful for architects to understand.

Provide a pragmatic way to implement solutions that are based on best practices.Provide architects with a real-world implementation of how to automate the architecture-design

and architecture-description processes.

For practicing architects, we will show real-world implementation of addressing the design of

architectures by using a set of pragmatic tooling. The Enterprise Architecture Toolkit (EATK) is usedto help us articulate how the role of documentation has changed. It does so by providing a series of

add-ins and templates to the tools that are used by mainstream architects and developers: Microsoft

Office tooling. The EATK provides a set of add-ins, templates, and processes that expose a richfeature set that we will use as the basis for this article. By doing so, we will make this article directly

gmatic Approach to Describing Solution Architectures http://msdn.microsoft.com/en-us/library/dd451087.asp

24 28/02/2012 10:54 AM
http://www.docu-track.com/buy/http://www.docu-track.com/buy/http://msdn.microsoft.com/en-us/library/dd451087.aspxhttp://www.docu-track.com/buy/http://www.docu-track.com/buy/http://www.docu-track.com/buy/http://msdn.microsoft.com/en-us/library/dd451087.aspx


2/24

relatable and actionable to the reader.

We will discuss how the Microsoft Office suite of productivity tools (Office Word, Office Excel, Office

PowerPoint, and Office Visio) is used today and how it can be extended by using the EATK. The EATKwill expand on one primary tool: Office Word 2007. Excluded from the scope of this article are the

developmental processes, tools, and other non-architecturerelated topics that are at a lower level of

abstraction than architectural activities.

Readers who are architects, process managers, and project managers will find the most value from

this article. However, this should not preclude other roles from learning about these concepts, asthey might be the consumers or stakeholders of the ideas that this article presents.

Goals of Article

Current architecture documentation does not live up to the promise of providing return on

investment in the design process. Often, the design that is articulated in architecture documentation

is not realized in the final implemented design that is hosted in a production environment.

The goal of this article is to provide guidance on how to solve common challenges with current

architecture documentation. It will do so by going over a series of add-ins and templates that the

EATK provides.

Areas that will be explored in this article are the following:

Alleviating challenges w ith current documentsTemplates and new thought-provoking

ideas will be introduced that challenge the existing ways of documenting architectures.

Living architecture designsDesigns often are static and do not have a life outside of the

development life cycle. We will introduce ways to change that.Enhancing decision supportOften, there are templates and checklists that give an architect

a common way to think about problems. This is an accelerator to solving problems that have

yet to be solved or identified.

Deriving to solutionsGiven how the human mind works, writing down a design to a specificproblem in "black and white" often shows gaps in current thinking.

Common means of co llaborationThese provide a working information store to share and

collaborate on architectures with team members.Supportability and maintainabilityDocuments provide important information on how asystem was built. This provides support personnel with vital information for solving

postproduction issues. For architects, the understanding of current system architecture will

allow them to build out a set of strategies for the enterprise.

A Brief History

Looking back, documents were not used in an isolated manner. They had supported a greater process

that governed how we created software. These processes became mature process frameworks.

Facilitated by frameworks, more sophisticated and resilient software solutions could provide a higher

level of predictability in software.

Figure 1. History of process frameworks for development and architecture


24 28/02/2012 10:54 AM
http://www.docu-track.com/buy/http://www.docu-track.com/buy/http://www.docu-track.com/buy/http://www.docu-track.com/buy/http://msdn.microsoft.com/en-us/library/dd451087.aspxhttp://www.docu-track.com/buy/http://www.docu-track.com/buy/http://www.docu-track.com/buy/http://msdn.microsoft.com/en-us/library/dd451087.aspx


3/24

As Figure 1 shows, there have been many process frameworks over the years. Each has its uniqueset ofapproaches. However, a common trend with them is the use of documentation in the process. It

is used both to drive the process and to document what is to be built.

This pervasive growth of documents shows how critical the information that is contained is to the

support of the software-development life cycle (SDLC). We now see the same with the support of

architecture efforts, too. There are a number of challenges that occur with this paradigm.

The Reality of Current Architecture Documentation

The unfortunate result of all of this documentation that exists just to support the process is that it

has created an unnecessary level of intrusiveness into the software-development and software-

architecture processes.

Figure 2. Documentation, increasing at an increased rate

As Figure 2 shows, we are adding more and more documents to an already large portfolio of

documents that must be completed. In the past, this was manageable; now, however, documents can

be bloated, and there is a higher probability of information being duplicated. Often, this is a result of

tightly coupling a document with a process step.

The challenge areas that we will be addressing in this article are the following:

ToolsOur existing tool suits have capabilities that we have yet to tap into. Challenges withword-processing tools have included:

Managing interfaces that have been designed for word processing, instead of forarchitectural design.

Collecting and managing information in multiple places in the organization.

Duplication of i nformationInformation redundancy is a substantial issue in the

architectural process. It leads to:Data-accuracy issues between sources and destinations.

Duplication of data entry.

Information that is subject to author interpretation and easily used out of context.

ProcessCurrent methods do a poor job of supporting the process. Processes have turned intomore of a checklist instead of a robust process. Challenges include the facts that:

What was designed often is not what is deployed. There are difficulties with tracking

these today in documents.

Information often is irrelevant after the application has been deployed.

Consuming information in other enterprise processes often is problematic.CollaborationHaving a connected experience with other architects in a word processor is

problematic and turns into a process-intensive effort with logistics of a documentfor example,

dealing with file shares, versioning, and tracking.

InformationConsistency and quality of information is based on the individual who authorsthe document. There is no real guarantee that all concerns will be addressed.

With these challenges, there is an opportunity to enhance and solve. As mentioned earlier, we willexplore these challenge areas and provide a set of solutions that will help architects in their

enterprise.

Rethinking the Traditional Architecture Document

Traditionally, architects have been forced to develop architectures in a restrictive and monolithic

waymeaning that the input mechanisms for architecture require a set of fairly sequential steps in


24 28/02/2012 10:54 AM
http://www.docu-track.com/buy/http://www.docu-track.com/buy/http://www.docu-track.com/buy/http://www.docu-track.com/buy/http://www.docu-track.com/buy/http://www.docu-track.com/buy/http://msdn.microsoft.com/en-us/library/dd451087.aspxhttp://www.docu-track.com/buy/http://www.docu-track.com/buy/http://www.docu-track.com/buy/http://msdn.microsoft.com/en-us/library/dd451087.aspx


4/24

which the information is derived. The question now is: Are the existing tools that we use forarchitecting outgrown or outdated for the tasks at hand? The answer here is: No, the current tools

still are used for mainstream development of architectures.

The most common and pervasive interfaces for architecture and design documents is Office Word.

Office Word is part of the Microsoft Office suite of productivity tools. With documentation, there are

many other tools that play a role in the documentation processes.

However, Office Word is not the only tool that is used in the architectural processes. There are many

other tools that have roles to play in how we document our architectures. These tools include thefollowing:

Office VisioUsed to model and visually describe interaction between objects. Model-driven

development (MDD) or generic models can be performed here. The architecture document is

used to describe the models and how they interact with other information that is notrepresented in the model.

Office Pow erPointA way to convey architecture for various purposes. These include

proposal of new ideas and patterns, and validation of architecture through a review board. The

architecture document often is the source for these presentations.Office ExcelThe tool of choice for matrices and analytical algorithms. The analytics are one

of many inputs in the architecture document.

Office SharePointOffers a strong capability in Rich Enterprise Content Management.

Workflow and review check-in and auditing can complement and simplify the process. Thearchitecture document is in need of these services.

It is important to understand the context in which these tools interact. Figure 3 shows an illustrationof how other productivity tools play a part in architectural processes. You might find that there is

applicability of other Microsoft tooling here; however, it has been excluded. The scope of this article

is to look at productivity tools specifically.

Figure 3. Other productivi ty tools playing a role in the documentation process

We can assert quickly that there is not just one tool that is used in the documentation of

architecture; myriad tools are used for collecting information from or publishing to. If we want to

solve the challenges with the process, we should keep this concern in mind.

For the rest of this article, we will focus primarily on the role of Office Word and the documents that

it produces. On occasion, however, we will reference other tools as they relate.

In the previous section, we discussed that challenges with word-processing tools have included:

Managing interfaces that have been designed for word processing, instead of for architectural

design.

Collecting and managing information in multiple places in the organization.


24 28/02/2012 10:54 AM
http://www.docu-track.com/buy/http://www.docu-track.com/buy/http://www.docu-track.com/buy/http://www.docu-track.com/buy/http://www.docu-track.com/buy/http://msdn.microsoft.com/en-us/library/dd451087.aspxhttp://www.docu-track.com/buy/http://www.docu-track.com/buy/http://www.docu-track.com/buy/http://msdn.microsoft.com/en-us/library/dd451087.aspx


5/24

Instead of answering these questions directly, let us discuss first how native capabilities can solvethese problems, as well as other problems that we might not have thought about yet.

There are some intrinsic capabilities that we can leverage from the tooling itself. We will explore thisfurther in two abstractions. When we refer to the architecture document, we will be talking about two

concepts:

Architecture documentThe architecture document itself, the templates, and the information

that is found within

Office Wo rdThe interface that supports the document and other extensibility points thatallow for interaction with other services in the enterprise

Why Not Use Other Technologies?

Many technologies could solve this relatively straightforward problem. However, the goal of this

article is to change fundamentally how architects think about the problem. Instead of starting from

the technology side, let us start from the problem outward. As discussed earlier in this article, the

focus is to describe architectures through Microsoft Office tools.

Figure 4 shows one way to think about why using Microsoft Office tools is ideal for enterprises to use

this method over others:

Figure 4. Cost versus time to deliver

Microsoft Office provides ways to reduce complexity and cost significantly. These are easy to

understand, and most users already have them on their desktops. Augmenting the existing Microsoft

Office tools to make them fit the usage of architects is particularly ideal; it maintains a consumable

amount of complexity, while limiting the overall cost.

There are other reasons for choosing this method. These drivers include the following:

CostMature enterprise-architecture (EA) tools often specialize in specific areas of architecture

management. This fact forces enterprises to have to acquire multiple tools in a suite to solvethe majority of their EA needs. This, in turn, leads to cost overruns and continually incurred

costs to operate architecture in IT.Currently used toolsData from leading industry analysts shows that upwards of 80 percent

of enterprises use productivity toolsthat is, Office Wordto describe their architectures. This

might not be optimal; it is, however, the most popular way to describe architectures.


24 28/02/2012 10:54 AM


6/24

AppetiteThe appetite for the purchase of enterprise-architecture tools has not grown muchover the years. Data shows that although there is some growth, it is usually in niche areas.

Model-driven development maturityModel-driven development can add complexity, and it

is prone to misuse and misunderstanding. While excellent tools are available (for example,

Microsoft Visual Studio Team System Architect Edition version 10) that can be very useful indocumenting architectures, they have a high bar for adoption. This high bar includes training or

a prerequisite of understanding of both the tool and languages, such as UML.

User experienceTechnologies such as Microsoft Office InfoPath could be used to describe

architectures, but they lack the flexibility and usability of Office Word.

TrainingWith new tools come new training requirements in process, methodology, and toolmechanics. Significant costs are incurred as the staff understands how to use (and adapt

current processes to) the tool of choice.

Despite the fact that Microsoft Office is used to describe architectures in this article, it should not

preclude architects from using other tools to implement these methods. The EATK solution that is

discussed primarily in this article can be extended to myriad Microsoft technologies, such as the

following:

Microsoft Visual Studio Team System

Microsoft Portfolio ServerMicrosoft Project Server

Microsoft Office InfoPath 2007

Optimizing Off ice Word to Describe Architectures

As mentioned earlier, Office Word is used as the primary tool for documenting our architecture;

however, the issue here is that it is less than optimal for solving some key issues in architecture. To

change the role of Office Word, we must change the context in which we use the tool.

Changing context is sometimes not an intuitive task. It takes some investigative work on both the

capabilities that you want to expose and potential development to the tooling.

The underlying goal is to change the role of Office Word from simply a word processor to more of a UI

for designing architectures. Applying structured UI concepts to Office Word provides many benefits to

the architecture document, including the following:

Structured contentInformation can be better described in the document. We want to do this

because of the challenges mentioned regarding how information does not integrate well with

process or future design activities. One example is the process of importing a model into anarchitecture document. Often, we import a picture that represents a model of the specific

viewpoint of an architecture. If we had an information model, we could specify that the model

imported is indeed the logical model, instead of a generic image file.

ExtensibleWith a little more structure, information has meaning and definition. This makesthe information extensible to other processes downstream.

ConsumableAbilities to consume external content is also possible with a more structured

interface. As an example, if you so choose, you could import external architecture information

from other systems to automate your design efforts.

By adding structure to Office Word, we build an information model behind it. This model supports the

information that is typed into the document itself. This is not uncommon from other tools such asOffice InfoPath. So, why are we not using Office InfoPath for an architecture document? In this case,

the rationale for not using Office InfoPath is twofold:

User adoptionThe largest challenge that enterprises face is adoption of new tooling. Instead

of introducing yet another tool for architects and developers to learn, navigate, and use, we

provide them with the current Office Word tooling that they have been using all along for

describing architectures

Information contextOffice InfoPath is very structured (maybe too structured) for thesepurposes. Office Word still provides flexibility for creativity in designs.

By looking at Office Word and Office InfoPath, it is clear that Office Word is the ideal tool for astructured UI. Changing the interface takes some thought, but is not a large development effort.

Through the use of the Office Word 2007 features that center on XML, we can truly start to extend

this interface. These features combine to help template authors create templates that are more


24 28/02/2012 10:54 AM


7/24

reliable, more stable, and rich.

Content controlsNew in Office Word 2007, content controls are predefined blocks of content

that you can position anywhere in the document. Example content-control types include textboxes, drop-down menus, calendars, and pictures. You can map most content controls to

elements in XML data attached to a document. You can easily map this XML data by using the

Office Word XML Format.

XML mappingThis feature of Office Word enables you to create a link between a documentand an XML file. This creates true data/view separation between the document formatting and

custom XML data.Office Word XML FormatThe Office Word XML Format (Word XML Format) is based on the

Open Packaging Conventions. Its main purpose is to divide the file into document parts, each of

which defines a part of the overall contents of the file. This feature enables you to editsomething in the file, such as the header or footer, without accidentally modifying any other

XML document parts. Similarly, all custom XML data is in its own part, so that working with

custom XML is easier now.

Building the new UI for the architecture documents is easier in Office Word. A series of out-of-

the-box functions are provided in the Office Word interface. For the architecture document, we will

use the built-in tools that Office Word provides to create this new UI, which will enable us to describeour information in a meaningful way.

Figure 5. Designer ribbon

Figure 5 shows the Designer ribbon. This ribbon provides the tooling that is necessary to create

content controls, map information to a schema, and extend the interface to third-party systems. Youmight have to enable the Designer ribbon. You will have to enable it though the Office Word Options

via the Popular screen.

In the architecture document, we will create a series of custom controls that will bind the information

that is typed in the interface to an XML structure. Figure 6 shows an image control for a logical

model. This is an example of how we can link information such as images and text to an XML

structure that will fully qualify the information.

Figure 6. Example of content control in architecture document

The Architecture of the System-Architecture Document

The architecture methods behind the implementation of a system-architecture document is not as

simple as defining a template. To change fundamentally how architects use a system-architecture

document, we must look at what services Office Word provides to add additional capabilities that willautomate and create rich meta-data integration services.


24 28/02/2012 10:54 AM
http://www.docu-track.com/buy/http://www.docu-track.com/buy/http://www.docu-track.com/buy/http://msdn.microsoft.com/en-us/library/dd451087.aspxhttp://www.docu-track.com/buy/http://www.docu-track.com/buy/http://www.docu-track.com/buy/http://msdn.microsoft.com/en-us/library/dd451087.aspx


8/24

For this solution, changing the context of Office Word is essential. By altering Office Word from aword processor to a UI, we can look at Office Word as an application instead of a closed environment.

The Microsoft Office environment provides rich extensibility that will allow developers to extend in a

meaningful way. To do so, an architectural approach will have to be taken. By separating out layers

and capabilities, approaches and technologies can be identified to derive to the right solution.

Figure 7. Architectural layers

As Figure 7 shows, there are four architectural layers that expose discrete services for this solution.

These include the following:

PlatformThis is what the solution-architecture document and the integration services

connect to. The platform components integrate with Office SharePoint Application Server

environment for rich line-of-business (LOB) integration.ToolThe mechanism of Office Word is referred to here. The tool provides extensibility into the

UI that provides Microsoft Office ribbons to execute tasks easily with a level of context and

Microsoft Office task panes that extend the UI with additional entry or listings of information.

DocumentThe document provides the way in which a user can enter architecturedescriptions. This is different in the EATK, as the document acts as the glue between the tool

and the information itself. This is accomplished through an architecture-document template and

the use of Office Word custom controls.

InformationThe information in the document is managed completely different from atraditional document. All of the information that is typed into the document is linked back to an

XML node behind the scenes. This fully qualifies what is typed. Not only is the information rich,

but it is extensible.

Platform Architecture

A great deal of work has been done in building componentized add-ins at the tooling level in Office

Word, but this is not enough to change fundamentally the architecture document into a tool fordesigning architectures. The components that are applied to Office Word build upon a larger

architecture canvas. The EATK provides a server-side Architecture Portal and Architecture Meta-Data

Repository (AMR). This architecture interacts with the document-level activities when we create an

architecture design.

Figure 8 shows a logical representation of the architecture that the EATK provides. It leverages a


24 28/02/2012 10:54 AM
http://www.docu-track.com/buy/http://www.docu-track.com/buy/http://www.docu-track.com/buy/http://www.docu-track.com/buy/http://www.docu-track.com/buy/http://www.docu-track.com/buy/http://www.docu-track.com/buy/http://msdn.microsoft.com/en-us/library/dd451087.aspxhttp://www.docu-track.com/buy/http://www.docu-track.com/buy/http://www.docu-track.com/buy/http://msdn.microsoft.com/en-us/library/dd451087.aspx


9/24

series of Microsoft-platform technologies, which include the following:

Microsoft Office SharePoint (MOSS) 2007Used as an Architecture Portal, Document

Management Services, and WorkflowWindow s Workflow Foundation (WF)The hosted workflow on the portal that interacts

with the desktop application and add-ins

Microsoft P roject ServerCan be used as the platform for interacting with project and

portfolio dataMicrosoft SQL ServerUsed as the database platform for the AMR that the Office Word

add-ins Patterns Browser and Architect Lookup will use to get their informationMicrosoft I IS 7.0Used as the hosting platform for the AMR Services layer

Figure 8. Archi tecture behind EATK system-architecture document

The server components in the EATK play a part in how we change the role of an architecture

document. All of the components on the server leverage platform capabilities of Office SharePoint,

but change the context in which they can be used. The context is the architecture-development

process. In doing so, we can take generic capabilities such as Enterprise Content Management (ECM)

to automate how information is audited and versioned.

The following are new interfaces and EATK components that were developed specifically for thearchitectural process and to interact directly with the system-architecture document:

AMR Web ServicesServices layer that allows for programmatic interaction with the AMR. It

provides extensibility into not only the AMR, but also other related services such as PPM orApplication Portfolio Management (APM).

AMR Data ServicesThe base information services that delivers information such as patterns

and existing IT assets to the Office Word task panes.

Document-Management ServicesAn Office SharePointbased set of services that are usedto manage documents. It comprises functionality such as check-in, auditing, versioning,

integrating with workflow, security, and archiving.

Workflow ServicesWF is used as the base of the workflow capabilities. Also, it is hosted on

the server, which allows the architecting workflows that are applicable to the entire enterprise,instead of to just one architect.

For more information on how to develop ribbons, please review the following articles:

Whats New for Developers in Office Word 2007


24 28/02/2012 10:54 AM


10/24

Building Word 2007 Document Templates Using Content ControlsMapping Word 2007 Content Controls to XML

Tool Architecture

Here, we examine both the architecture of the tool (or the product) Office Word and how to extend

this tool to meet the needs of architects when they describe their architectures. As discussed earlier

in this section, we want to change Office Word into a UI. To do so, the tool must allow for extendingthe UI.

This aspect of the solution is key to bridging the system-architecture document to both the platformfor LOB integration and the document itself, which will be the interface in which architects will

describe their solutions. All of the application logic is encapsulated in this layer. Because this is the

layer in which code is developed, this solution is dependent on Office Word API and other standard

integration technologies.

Open standards are a first-class citizen in this solution. The ability to extend the UI by using standard

technologies and standards increases the ability of this solution to be accepted and adopted with yourorganization.

The standard technologies that are supported include the following:

XML

Open XMLWeb services

Microsoft .NET Framework 2.0 Support

ADO.NET

By using these open standards and technologies, integration with third-party or LOB solutions is

dramatically easier. Specifically, we use these technologies in the EATK to provide rich information

that is tailored to the needs of architects.


f 24 28/02/2012 10:54 AM
http://www.docu-track.com/buy/http://msdn.microsoft.com/en-us/library/dd451087.aspxhttp://www.docu-track.com/buy/http://www.docu-track.com/buy/http://www.docu-track.com/buy/http://msdn.microsoft.com/en-us/library/dd451087.aspx


11/24

Figure 9. Components of Office W ord interface

Figure 9 shows the extended capabilities of Office Word. We have extended the following aspects of

Office Word:

RibbonsCreating ribbon components allows us to create executable functions that can launch

from Office Word. We use this functionality as a launch pad for downstream activities, workflow

triggering, collaboration, and information retrieval.

Task panesUsing task panes allows us to extend functions of Office Word and retrieveinformation from other sources. We can use this functionality for various aspects in which we

want to create other interfaces from within Office Word.

PropertiesAssigning metadata to a document can be performed through the Properties pane.

Also you can create your own custom properties.

System-Architecture Document Ribbons

The first area that we will explore in the extension of the Office Word interface is custom ribbons. As

described in the previous section, ribbons allow us to display a launch pad of functions that can be

executed. We will not be going into the development aspects of the ribbon; instead, we will talk about

the functionality that we want to expose.

For the interface of our system-architecture document, we want to have a series of functions that

relate directly to architectural processes and information.

Figure 10. Ribbon components of system-architecture document

As Figure 10 shows, there are four ribbon components in the EATK:

Patterns SearchYou can launch a ribbon component to execute a search against the


f 24 28/02/2012 10:54 AM


12/24

knowledge-management aspect of the AMR. A task pane is launched upon clicking the PatternsSearch ribbon component. It displays patterns and existing IT assets that will help solve specific

architecture-design questions and challenges.

Patterns BrowserWith a similar launching functionality as the Patterns Search, the Patterns

Browser gives architects the flexibility of discovering patterns by navigating through a series ofviews on Assets and Patterns in the Patterns Browser task pane. This is a new way of extending

information in Office Word. It allows for surfacing the right patterns in a more intuitive way for

solving a business problem.

Architect LookupLooking up an architect who is assigned to a project is streamlined with

Architect Lookup. This ribbon component launches the Architect Lookup task pane that willdisplay a list of architects and the photos of those who are on the same project or program.

Linked via Project Portfolio Management (PPM), this ribbon component combines two very

powerful aspects of the architectural process. It can accelerate how an architect collaborates

with other roles on a project to have every view of the architecture satisfied.Upload DocRemoving complexities in processing architecture information reduces

unnecessary organization of information. This ribbon component ensures that information that

was written in the document is consumed into workflow and information stores on the server.

Figure 11. Architecture ribbon-component interaction, with Office Word as UI

As Figure 11 shows, there is a series of interactions that occur with both the Patterns Search and the

Patterns Browser. The steps are as follows:

Invoke the Architect Lookup task pane.1.

Auto-populate the task pane.2.

Invoke the Patterns Search with a query.3.Display the hierarchal results of that query.4.

Additional areas of functionality that are not in the EATK but that also can be explored are deeperintegration with workflow, collaboration, and communication. Examples are as follows:

Distribute document. Break up the document into specific topic areas that can be consumedby a specific role owner of the document.

Retrieve architecture views. Many times, an architect wants to use a tool other than Office

Word for a model or specific content. With this component, a user can use another tool (for


f 24 28/02/2012 10:54 AM


13/24

example, an information-modeling tool) to create a model. That model can be imported into theAMR. After that is done, meta-data is associated with that modelputting classifiers on it t hat

assign the model to an architecture. This ribbon component then will pull all related information

for the architecture that is being worked on. It will retrieve the model and insert it into the

document.Generate Office Pow erPoint slides. Looking at the role of Office PowerPoint in the process,

we see that it is used to communicate and vet ideas within a specific community. Whether it is

to validate or propose new ideas, the purpose is still the same. When using Office PowerPoint in

this way, there is a great deal of rework and duplication of effort. This ribbon component allows

for templates to be created to which information in the architecture document can be exported.

System-Architecture Document Task Panes

The second mechanisms that we can use in this context are task panes. Task panes can be very

useful to architects, as they can surface meaningful information at a moments notice with a click of a

ribbon component. The ribbon components that were described earlier and the tasks panes have aclose relationship. Because ribbons are merely a function launcher, there is not a UI. This is where

task panes play a part in the Office Word UI. Clicking on a ribbon component allows a tailored UI to

be shown in Office Word. Not all ribbons invoke a task pane, but there are many functions that do.

Task panes allow us to perform the following functions:

Interact with information in a task pane as many other UIs, such as right-clicking and opening

new windows

Drive down to information from other applications and information stores

Import information from a task pane into documents

Pull information into this environment conveniently

This information is not only visible, but also interactive. One way to interact with the information is

to have information in the task pane entered into the document.

Figure 12. Task-pane usage in system-architecture document

The EATK has a series of bundled system-architecture document task panes. These task panes

automate the architecture-development process.

The following are the task panes that the EATK provides:


f 24 28/02/2012 10:54 AM


14/24

Patterns SearchAllows the architect to enter a set of keywords that returns informationback to the task pane.

Patterns BrowserAs shown in Figure 12, allows an architect to navigate the knowledge-

management aspects of the AMR to retrieve.

Architect LookupShows the architects who are assigned to the current development effortof an architecture. Photos of the individuals and collaboration features allow this task pane to

be more than just an information display.

The Patterns Search and the Patterns Browser are similar in functionality. They both display asset

and pattern information from the AMR. The Patterns Search allows for text-based queries into theAMR, whereas the Patterns Browser pulls the entire pattern library, so that it can be browsed.

The intent of the Patterns Search and the Patterns Browser is to surface pattern information into the

design environment.

Two types of information are displayed:

AssetsShows what has been built. Assets in this context are architecture representations ofsystems and applications in an enterprise. These architecture assets have views associated with

them. All architectures will have discrete views associated, to ensure the right level of

abstraction. These views correlate with the sections in the system-architecture document.

PatternsShows what should be built. Patterns contain reusable building blocks that aid

architects in their designs. The patterns in this case are defined loosely in nature to ensureoptimal usage in an enterprise. (We will cover the hierarchy of the information later in this

section.)

There are many tangible benefits to having such task panes. Increasing visibility into this information

is essential to the success of an IT organization. These task panes surface information that

traditionally would be stored in various documents, Web sites, or proprietary tools. By extending thisinformation directly into the tools in which they are applied, an enterprise can increase its adoption

of patterns.

Tangible ways in which these task panes empower IT architects are the following:

Systematic reuseMany of the architectures that we build have repeatable patterns builtwithin. By surfacing patterns in a composite manner, we can reuse the aspects and views of

architectures in a systematic way.

Decision supportBy reviewing existing architectures, we can review how solutions were

developed based on a set of drivers. Not only can you review, but also you can contrast

decisions on these architectures with the challenges of the current architecture efforts.AutomationNot only can you view the patterns and assets in the task pane, but also you can

apply them to your architecture design. By reusing models and architectural descriptions, you

can automate the architectural process by eliminating unnecessary work.

Traceability of technology choicesNot only can you surface this information and apply itto your architecture designs, but now you can create relationships between what was imported

and the architecture that you are designing.


f 24 28/02/2012 10:54 AM


15/24

Figure 13. Interacting w ith elements i n document

As Figure 13 shows, patterns can be applied to the elements of an existing architecture. In the

preceding case, it is the reuse of a logical architecture model. Appling the selected model is as easyas double-clicking the pattern in the Patterns Browser. The pattern then is applied to the element

that is selected in the document.

The information that is displayed in the task pane is tailored in a unique way. Scope and context are

important factors when you are trying to find the most appropriate content. The Patterns Browser

surfaces information from the AMR in a way that shows the information in a much more consumable

manner.

The information is organized in the following ways:

Information typeAt the root level, defines the two major branches of information. As

described previously, each has its own purpose:

AssetPattern

ViewpointsOrganized information in specific viewpoints that are tailored for specific

purposes.

Techno logy (.NET, ADO, JSP, and so on)When you know the technology that youwant to use, you can go right to it and select the appropriate information.

Business (ATM, lending)When you must derive to a technology solution or pattern

from a set of business concerns, you will want to use the business viewpoint.

Architecture (*-ilities)By pivoting off of the architecture viewpoint, you can navigate

through patterns that have architecture concerns in mind.

The architectural process no longer is just a one-architect job. With the regulatory enforcement of

separation of duties and the need for a streamlined enterprise IT environment, changes are occurringwith the architect role. There are multiple architects who have specific roles in the design of system

architecture. These roles could be Application, Information, Hardware, Security, or Infrastructure

architect. Usually, enterprises have their own names for these roles. This is not the exhaustive list of

roles, but instead an example of roles that can play in the architectural process.


f 24 28/02/2012 10:54 AM


16/24

Figure 14. Collaborative architectures

Figure 14 is an illustration that further articulates the collaboration between roles in the enterprise.

This collaboration spans across the process, too. We see that there are not only interactions with

multiple roles, but also process steps and tasks. Here, with the SDLC, we can get a holistic view ofwhere collaboration plays in the overall process of architectural design.

Each role has a part to play in the architectural process. Given the illustration in Figure 14, we seethat an Application architect might start the process, but then might need the aid of other architects.

In this case, the Application architect might be the owner of the document and be the primary

contributor. The other roles that are shownsuch as Hardware architect, Security architect, and

Information architectare some that would interact. These roles will validate, add, and modify

architecture-design descriptions.

In this context, a sample of common questions to these roles would look like the following:

How will the security model affect how I design my application?

I know that I must design an external portal, but what does the server-tier model look like for

the DMZ?What will the network stack look like, and how will that affect performance or scalability?

What is the right hardware platform to use, based on my solutions-cost-to-functionality ratio?

Although the questions change, the premise is still the same. The Application architect in this

scenario will have many questions about other crosscutting architecture domains to ensure that their

application architecture domain is architected in the right manner.

Other roles in review processes will have an impact on the validity, quality, and level of completeness

of the designs. This affects the architecture in a significant way, too. These roles usually are part of

an Architectural Review Board of sorts. In this function, it is critical that the architecture documentgive this group of individuals the information that it needs to make decisions on the architecture. By

introducing the collaborative aspects to the architectural process, we can reduce the number of issues

ahead of time, instead of at the end of the processthus, changing the architecture-design process

from its current form of a reactive process to a proactive process.

Ultimately, this streamlines the process by reducing the amount of rework that potentially would

have to be performed by the architect. Also, quality will rise with the reduction of technology silos. By

leveraging subject-matter experts (SME) in a specific domain, the Application architect can get verydeep and tailored guidance for an aspect of the architecture.

To facilitate collaboration in the architecture-design process, the EATK has an Office Word add-in thatis called Architect Lookup. This task pane enables collaboration right from the system-architecture

document itself. From within the task pane, we can surface information from a variety of information

stores that will give us a tailored collaboration experience for the architectural process.


f 24 28/02/2012 10:54 AM


17/24

In the collaboration scenario that Figure 14 shows, there is a need to discuss architectural issues andquestions. Architect Lookup is a tool with which you can collaborate immediately with Hardware,

Security, and Information architects as you work through the document. Without knowing the specific

person to talk to, an architect can retrieve a listing of the architects who are assigned to the project.

By simplifying the process of determining the right people to talk to, architects can spend more time

on architecture, instead of on project management. Specific goals of Architect Lookup are to:

Support collaborative architecture design.

Increase visibility of the roles that are assigned to a project.Obtain answers to questions early in the process.Provide a seamless and simple interface for retrieving architect information.

Link into interactive capabilities, such as instant messaging (IM) and video conferencing.

When we look at the implementation of Architect Lookup, we see that it uses meta-data from thesystem-architecture document. Each system-architecture document has a standard set of meta-data

assigned to it. One element of this meta-data is the project ID. The project ID is the unique identifier

that links the architecture design that is being worked on in the document with a project that is

catalogued in a PPM tool. For the sake of this architecture, we will be using Project Server.

The technologies that are used for Architect Lookup are the following:

Project ServerProvides the list of architecture roles and resources on the project.Active DirectoryValidates the identity of a resource.

Office SharePointSurfaces the images, and links to My Sites and IM.SQL ServerThe AMR is used to retrieve the project ID of the architecture, if needed.

By using the meta-data that is readily available to Architect Lookup, it can retrieve the resourcesfrom Project Server. There are other technologies that play a role, too. These roles were described

earlier.

If we look back at our scenario, Architect Lookup would return the names and photos of the

Hardware, Security, and Information architects.

Figure 15 shows an example of this:

Figure 15. Architect Lookup task pane

As Figure 15 shows, the Architect Lookup task pane reveals the architect resources, based on theproject that is assigned to the architecture work. The way in which Architect Lookup determines this

is by using the assigned project ID. The project ID is found in the meta-data of the document. This


f 24 28/02/2012 10:54 AM
http://www.docu-track.com/buy/http://www.docu-track.com/buy/http://www.docu-track.com/buy/http://www.docu-track.com/buy/http://www.docu-track.com/buy/http://www.docu-track.com/buy/http://msdn.microsoft.com/en-us/library/dd451087.aspxhttp://www.docu-track.com/buy/http://www.docu-track.com/buy/http://www.docu-track.com/buy/http://msdn.microsoft.com/en-us/library/dd451087.aspx


18/24

meta-data can be entered either manually or through automated means when the architecture-design request is sent.

Architect Lookup will take the project ID and perform a query against multiple systems to return a setof results. Project Server (or a custom information store) can be used to retrieve the list of architect

resources, while Office SharePoint and Active Directory are used to take the resources in the PPM

repository and correlate them with the images of the person, along with links to IM and personal

portal sites.

Use of Architect Lookup eliminates the need to go to project plans, portals, or file shares to find thisinformation manually. It is a simple click away to get instant access to other resources on the project,to get answers to questions.

Document-Template Architecture

Along with enhancements to the tool, the next layer of concern is the document template. The

document template is not unlike a traditional template. In this case, the EATK solution provides

architects with a starting point on a template.

The template has a set of architecture views that are defined with corresponding data elements. This

will give architects a starting point in defining their own template or simply reusing the template.

The document-template layer does not have a great deal of intelligence to it; however, it does allow

interaction from Office Word to the document. One example is that the EATK allows information froman external source to be clicked and dragged into the document. This pulls data from a database

and populates the document with architecture models.

The EATK provides not only the Office Word add-ins that are described in the previous sections of this

article, but also a system-architecture document template, as Figure 16 shows:

Figure 16. System-architecture document template


f 24 28/02/2012 10:54 AM


19/24

The views that are listed in the table of contents are a set of common views. These views can berenamed or removed, and additional views can be added. These views provide a starting point for

architects. Whereas you can use the system-architecture document template as your corporate

standard in your company, it will be common practice to modify it. It is important to understand that

this solution provides one way of defining a template. The key is to help architects understand how toimplement this type of solution in their environments, not necessarily to use it out of the box.

With many documents that are surrounded by process, we want to create templates to ensure thatthey are used in a consistent way. This is the same case with the system-architecture document

template. A template for the architecture document will allow for:

Everyone using the right version of the architecture document.

Ensuring that the information models stay intact.

Allowing for information to be generated by the system.

Enabling information to be consumed by downstream processes.

There are several areas that we will discuss when it comes to templates. Each area is very important

to how the document is used in the architectural process:

Information modelAn information model is critical to the success of the system-architecture

document, as the information will be extended and correlated with other aspects of software

development. To do so, we must ensure that the information model is one that properly

describes the content and can correlate it with other information.System-architecture XMLThis is custom XML that is used to describe the information within

the document. Describing this information in the context of architecture allows the information

to be digestible by downstream processes.Open XML schemaOpen XML provides the necessary document structure for information to

be populated and extended into other uses.

Packaging the document templateTemplates provide a repeatable way to create

architecture documents.

Information Architecture

The last piece of the puzzle is the information itself. Having great add-ins and template is great;

however, without a meaningful way to express and ensure that the information is long living in aconnected process, it is not as useful as it could be. Without information architecture, it would be

difficult to qualify architectures.

The information layer is the base of the solution; it is where the majority of the consideration is

made. All layers interact with each other in some way, but the information layer is connected directly

to all. It is consumed in workflows, information-entry processes, and automation through MicrosoftOffice ribbons and task panes.

The EATK uses industry-standard techniques to derive to the target information architecture. Two

fundamental aspects of the EATK that we must explore are the following:

OntologyWe want to define a set of terms that are understood commonly within the

enterprise. By doing so, we can relate information properly and consistently.

TaxonomyThis will allow you to correlate architecture information with other aspects of

architecture.

Both of these aspects are critical to this process. There is a wealth of industry-accepted practices inthe standards community that accelerates our development. We should be using these industry best

practices in our IT organizations, to ensure continuity between custom-built applications and


f 24 28/02/2012 10:54 AM


20/24

commercial off-the-shelf (COTS) solutions.

Ontology can be difficult to derive to; however, as soon as it is done, it is invaluable. The archite cture

document should use the terms in the proper usage to qualify what the information is. Publishing anonline ontology mapping will be useful toward understanding the information within the document. In

the context of the system-architecture document, ontology provides agreed-upon terminology for

architecture. As an example, it would define the meanings of a platform, system, subsystem,

application, and components.

Defining what these architecture elements are, however, is one piece of the puzzle. How theseelements relate to each other is the next logical step. We will use taxonomy for this. The EATK usesan industry standard from IEEE to solve this challenge. IEEE 1471 is used as the basis for the

taxonomy and ontology of the system-architecture document.

IEEE 1471 is the first formalized standard for describing architectures and how they relate to otheraspects of the software-development process. It leverages a scalable meta-model that shows the

relationships between common elements in the architecture-development process.

Figure 17. IEEE framework for architectural description

In Figure 17, IEEE 1471 provides a meta-model that allows us to relate architectures with other

aspects of the software-development process. The system-architecture document focuses on specific

areas of the taxonomy, while other EATK components focus on other aspects of the standard.

The importance of this taxonomy is not completeness, but instead populating information into models

that can classify and relate information to each other. With IEEE 1471, we can do this in an industry-compliant way.

Elements that are supported in the system-architecture document are the following:

SystemSystems are described in length in the document.

ArchitectureThe basis of the system-architecture document is the notion of creatingarchitectures. EATK establishes a catalog of IT architecture assets; in doing so, it then can

create a link to the architecture taxonomy.


f 24 28/02/2012 10:54 AM


21/24

Architecture descriptionThe primary content of the system-architecture document wil l bedescriptions of the architecture and its subsequent views.

ViewThe EATK provides eight common views for architecture descriptions that are common

across most architecture efforts.

ModelModels are fully supported in and incorporated into the system-architecture document.EnvironmentThe environment and how to derive to the right one is supported fully in the

system-architecture document.

Closely related elements are implemented in the EATK:

RationaleThe most important part of the architectural process is how we derive to ourarchitecture decisions. EATK provides a process and tools for supporting the process of

architecture decisions.

To implement this in the EATK and the system-architecture document, there is a series ofconsiderations and trade-offs that must occur. In the system-architecture document, there is a

balance between structure and freedom of creativity.

The aspects that are implemented to support IEEE 1471 in the system-architecture document are the

following:

Structured contentAn architecture schema that represents the information that we want to

gather in our architecture document was created that has a viewpoint-based model applied toit.

Qualifying informationLinks between decisions that have been made and other systems orarchitecture descriptions are built into the schema. As a user enters information or applies

patterns to the architecture document, it will correlate that information by unique ID.

Publishing mechanismsProvides facilities to store information from the schema, so that it

can be related to other non-documentrelated information.Generating informationProvides a mechanism to rebuild or generate sections of an

architecture document.

System-Architecture M arkup XML

With an ontology and taxonomy for architecture, we now can look at what this means from animplementation perspective. The system-architecture document has an underlying XML structure thatis used to describe the information in the form of XML.

As Figure 18 shows, traditional documents are freeform. Information is entered in an ad-hoc way andrarely is digestible to downstream processes. This is a substantial problem, as architects spend a

great deal of time designing architecture in document form.

Figure 18. Changing document model

As Figure 18 shows, the EATK provides a template for how to tie information to an XML structure.This XML structure provides enterprises with an extensible system-architecture document data model.

This capability allows the EATK to change Office Word into a UI for architecture design.

The EATK provides a sample XML schema that is meant to be a starter XML structure that will allow

organizations to tailor their own architecture activities. The rationale for not creating a full

architecture XML structure was that most organizations use their own definitions and process

frameworks. The value of the architecture XML structure is the demonstration of the capability, notnecessarily the structure itself.


f 24 28/02/2012 10:54 AM


22/24

The structure also shows how an architecture XML structure can be applied in a real-worldarchitecture-design process. Because it is an example and implementation, it will greatly accelerate

efforts to build or repurpose the architecture XML structures that are used in the EATK.

Implementing the system-architecture XML, there are built-in facilities in the new Microsoft Office

Open XML file formats. These new formats were introduced in Microsoft Office 2007. With the new

formats, the entire document is XML-based. The document itself is a zip (compressed) file that has an

extension of .docx. In these files are a series of file folders.

The customXML folder is used in the EATK. In Figure 19, we see that item1.xml is the system-architecture XML file that is used for storing architecture information. All information that is enteredinto the system-architecture document will be stored here.

Figure 19. System-architecture XML fi le

The steps to retrieve information manually from the system-architecture document are the following:

Open Microsoft Office Word.1.

Click the Office button, and select New .2.Click the system-architecture document template, and select Create.3.

Populate the document with your architecture descriptions.4.

Save the document to the desktop.5.

Go to the desktop, and change the extension of the document from .docx to .zip.6.Double-click to open the document as a zip file. The file structure should be visible.7.

Double-click the Custom XML directory.8.

To open the XML file, double-click the item1.xml file.9.

The architecture XML file gives the system-architecture document a local data store that is carriedalong with the document. This opens up some interesting opportunities, when we look at how this can

be used (see Figure 20).


f 24 28/02/2012 10:54 AM


23/24

Figure 20. item1.xml fil e

Architecture content from other sources can be used from within the system-architecture document.

By integrating with other systems or processes, third-party tools could generate standard XML that

can be imported into the appropriate nodes in the architecture XML file.

To solve this and many other challenges, it is necessary to change the behavior of Office Word. To do

so, we must develop an architecture template.

Conclusion

In this article, we reviewed how to change fundamentally the way in which we view, approach, and

maintain architecture descriptions. There is no doubt that there could be significant value in

capturing information about the designs of our architectures that will help guide decision makersthrough the processes of making the right architecture decisions. However, this is not always the

outcome, as often no formalized structure, process, information model, or intelligent tooling is

bundled with this process.

Key takeaways include the following:

Architects who want to implement these concepts can use the EATK, which provides a set of

templates, processes, and a solution accelerator that can be used to accelerate thisimplementation for architects.

Architects can achieve significant productivity gains through reduction of manual activities andprocess automation.

Architecture information can be used in a much more meaningful way by eliminating the


f 24 28/02/2012 10:54 AM


24/24

2012 Microsoft. All rights reserved.

document graveyard effect, by integrating architecture descriptions with an AMR.The quality of decision making can be improved by eliminating points of duplication; thus,

information quality can be increased significantly.

Wikis and modeling tools complement this implementationor, in some cases, replace it.

Solutions such as COTS and custom-developed applications can be integrated with this solutionthrough standard integration technologies.

References

Microsoft Enterprise Architecture Center:

http://msdn.microsoft.com/architecture/EA

About the author

Mike Walker is a principal architect for Microsoft who is responsible for building the strategy formanaging, delivering, and communicating the Microsoft position on enterprise architecture. He is

responsible for driving Microsofts worldwide Enterprise 2.0 and Enterprise Architecture strategies in

key industry segments.

Mike joined Microsoft in early 2006. His background is as a financial-services enterprise architect and

strategist, specializing in business transformation around technology, strategic infrastructureplanning, portfolio management of technology projects, and solution architecture. As a thoughtleader, Mike combines this experience with a strong focus on strategic execution.

Visit Mike Walkers blog: http://blogs.msdn.com/MikeWalker

Did you find this helpful? Yes No

http://msdn.microsoft.com/architecture/EAhttp://blogs.msdn.com/MikeWalkerhttp://www.docu-track.com/buy/http://msdn.microsoft.com/en-us/library/dd451087.aspxhttp://www.docu-track.com/buy/http://www.docu-track.com/buy/http://www.docu-track.com/buy/http://msdn.microsoft.com/en-us/library/dd451087.aspxhttp://blogs.msdn.com/MikeWalkerhttp://msdn.microsoft.com/architecture/EA