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 Document
Optimizing 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 in obscure places on bookshelves, eventually to collect dust and be forgotten—something 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 has created 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 change fundamentally 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 used to 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 rich feature set that we will use as the basis for this article. By doing so, we will make this article directly 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 EATK will expand on one primary tool: Office Word 2007. Excluded from the scope of this article are the developmental processes, tools, and other non-architecture–related 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, as they 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 with current documents—Templates and new thought-provoking ideas will be introduced that challenge the existing ways of documenting architectures.
• Living architecture designs—Designs often are static and do not have a life outside of the development life cycle. We will introduce ways to change that.
• Enhancing decision support—Often, 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 solutions—Given how the human mind works, writing down a design to a specific problem in "black and white" often shows gaps in current thinking.
• Common means of collaboration—These provide a working information store to share and collaborate on architectures with team members.
• Supportability and maintainability—Documents provide important information on how a system 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

As Figure 1 shows, there have been many process frameworks over the years. Each has its unique set of approaches. 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:

• Tools—Our existing tool suits have capabilities that we have yet to tap into. 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.
• Duplication of information—Information 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.
• Process—Current methods do a poor job of supporting the process. Processes have turned into more 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.
• Collaboration—Having a connected experience with other architects in a word processor is problematic and turns into a process-intensive effort with logistics of a document—for example, dealing with file shares, versioning, and tracking.
• Information—Consistency and quality of information is based on the individual who authors the 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 will explore 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 way—meaning that the input mechanisms for architecture require a set of fairly sequential steps in which the information is derived. The question now is: Are the existing tools that we use for architecting 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 the following:

• Office Visio—Used 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 not represented in the model.
• Office PowerPoint—A 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 Excel—The tool of choice for matrices and analytical algorithms. The analytics are one of many inputs in the architecture document.
• Office SharePoint—Offers a strong capability in Rich Enterprise Content Management. Workflow and review check-in and auditing can complement and simplify the process. The architecture document is in need of these services.

It is important to understand the context in which these tools interact. Figure 3 shows an illustration of 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 productivity 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.

Instead of answering these questions directly, let us discuss first how native capabilities can solve these 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 this further in two abstractions. When we refer to the architecture document, we will be talking about two concepts:

• Architecture document—The architecture document itself, the templates, and the information that is found within
• Office Word—The interface that supports the document and other extensibility points that allow 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:

• Cost—Mature 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 solve the majority of their EA needs. This, in turn, leads to cost overruns and continually incurred costs to operate architecture in IT.
• Currently used tools—Data from leading industry analysts shows that upwards of 80 percent of enterprises use productivity tools—that is, Office Word—to describe their architectures. This might not be optimal; it is, however, the most popular way to describe architectures.
• Appetite—The appetite for the purchase of enterprise-architecture tools has not grown much over the years. Data shows that although there is some growth, it is usually in niche areas.
• Model-driven development maturity—Model-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 in documenting 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 experience—Technologies such as Microsoft Office InfoPath could be used to describe architectures, but they lack the flexibility and usability of Office Word.
• Training—With new tools come new training requirements in process, methodology, and tool mechanics. 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 Server
• Microsoft Project Server
• Microsoft Office InfoPath 2007

Optimizing Office 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 content—Information 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 an architecture 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.
• Extensible—With a little more structure, information has meaning and definition. This makes the information extensible to other processes downstream.
• Consumable—Abilities 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 as Office 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 adoption—The 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 context—Office InfoPath is very structured (maybe too structured) for these purposes. 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 a structured 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 reliable, more stable, and rich.

• Content controls—New in Office Word 2007, content controls are predefined blocks of content that you can position anywhere in the document. Example content-control types include text boxes, 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 mapping—This feature of Office Word enables you to create a link between a document and an XML file. This creates true data/view separation between the document formatting and custom XML data.
• Office Word XML Format—The 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 edit something 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 describe our 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. You might 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 will automate and create rich meta-data integration services.

For this solution, changing the context of Office Word is essential. By altering Office Word from a word 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:

• Platform—This 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.
• Tool—The 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.
• Document—The document provides the way in which a user can enter 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 an architecture-document template and the use of Office Word custom controls.
• Information—The information in the document is managed completely different from a traditional 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 for designing 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 series of Microsoft-platform technologies, which include the following:

• Microsoft Office SharePoint (MOSS) 2007—Used as an Architecture Portal, Document Management Services, and Workflow
• Windows Workflow Foundation (WF)—The hosted workflow on the portal that interacts with the desktop application and add-ins
• Microsoft Project Server—Can be used as the platform for interacting with project and portfolio data
• Microsoft SQL Server—Used as the database platform for the AMR that the Office Word add-ins Patterns Browser and Architect Lookup will use to get their information
• Microsoft IIS 7.0—Used as the hosting platform for the AMR Services layer

Figure 8. Architecture 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 the architectural process and to interact directly with the system-architecture document:

• AMR Web Services—Services 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 or Application Portfolio Management (APM).
• AMR Data Services—The base information services that delivers information such as patterns and existing IT assets to the Office Word task panes.
• Document-Management Services—An Office SharePoint–based set of services that are used to manage documents. It comprises functionality such as check-in, auditing, versioning, integrating with workflow, security, and archiving.
• Workflow Services—WF 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:

• What’s New for Developers in Office Word 2007
• Building Word 2007 Document Templates Using Content Controls
• Mapping 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 extending the UI.

This aspect of the solution is key to bridging the system-architecture document to both the platform for 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 your organization.

The standard technologies that are supported include the following:

• XML
• Open XML
• Web 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.

Figure 9. Components of Office Word interface

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

• Ribbons—Creating 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 panes—Using task panes allows us to extend functions of Office Word and retrieve information from other sources. We can use this functionality for various aspects in which we want to create other interfaces from within Office Word.
• Properties—Assigning 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 Search—You can launch a ribbon component to execute a search against the knowledge-management aspect of the AMR. A task pane is launched upon clicking the Patterns Search ribbon component. It displays patterns and existing IT assets that will help solve specific architecture-design questions and challenges.
• Patterns Browser—With a similar launching functionality as the Patterns Search, the Patterns Browser gives architects the flexibility of discovering patterns by navigating through a series of views 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 Lookup—Looking up an architect who is assigned to a project is streamlined with Architect Lookup. This ribbon component launches the Architect Lookup task pane that will display 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 Doc—Removing 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:

1. Invoke the Architect Lookup task pane.
2. Auto-populate the task pane.
3. Invoke the Patterns Search with a query.
4. Display the hierarchal results of that query.

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

• Distribute document. Break up the document into specific topic areas that can be consumed by 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 example, an information-modeling tool) to create a model. That model can be imported into the AMR. After that is done, meta-data is associated with that model—putting classifiers on it that 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 PowerPoint 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 moment’s notice with a click of a ribbon component. The ribbon components that were described earlier and the tasks panes have a close 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:

• Patterns Search—Allows the architect to enter a set of keywords that returns information back to the task pane.
• Patterns Browser—As shown in Figure 12, allows an architect to navigate the knowledge-management aspects of the AMR to retrieve.
• Architect Lookup—Shows the architects who are assigned to the current development effort of 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 the AMR, 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:

• Assets—Shows what has been built. Assets in this context are architecture representations of systems 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.
• Patterns—Shows 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 ensure optimal 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 this information 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 reuse—Many of the architectures that we build have repeatable patterns built within. By surfacing patterns in a composite manner, we can reuse the aspects and views of architectures in a systematic way.
• Decision support—By 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.
• Automation—Not 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 choices—Not only can you surface this information and apply it to your architecture designs, but now you can create relationships between what was imported and the architecture that you are designing.

Figure 13. Interacting with elements in 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 easy as 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 type—At the root level, defines the two major branches of information. As described previously, each has its own purpose:
  • Asset
  • Pattern
• Viewpoints—Organized information in specific viewpoints that are tailored for specific purposes.
  • Technology (.NET, ADO, JSP, and so on)—When you know the technology that you want 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 occurring with 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.

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 of where 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 see that 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 shown—such as Hardware architect, Security architect, and Information architect—are 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 document give 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 process—thus, 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 very deep 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 that is 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.

In the collaboration scenario that Figure 14 shows, there is a need to discuss architectural issues and questions. 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 the system-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 Server—Provides the list of architecture roles and resources on the project.
• Active Directory—Validates the identity of a resource.
• Office SharePoint—Surfaces the images, and links to My Sites and IM.
• SQL Server—The 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 resources from 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 the project 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 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 set of 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 this information 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 from an 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

The views that are listed in the table of contents are a set of common views. These views can be renamed 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 to implement 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 that they 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 model—An 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 XML—This 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 schema—Open XML provides the necessary document structure for information to be populated and extended into other uses.
• Packaging the document template—Templates 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 a connected 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 Microsoft Office 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:

• Ontology—We want to define a set of terms that are understood commonly within the enterprise. By doing so, we can relate information properly and consistently.
• Taxonomy—This 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 in the 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 commercial off-the-shelf (COTS) solutions.

Ontology can be difficult to derive to; however, as soon as it is done, it is invaluable. The architecture document should use the terms in the proper usage to qualify what the information is. Publishing an online 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 these elements relate to each other is the next logical step. We will use taxonomy for this. The EATK uses an 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 other aspects 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:

• System—Systems are described in length in the document.
• Architecture—The basis of the system-architecture document is the notion of creating architectures. EATK establishes a catalog of IT architecture assets; in doing so, it then can create a link to the architecture taxonomy.
• Architecture description—The primary content of the system-architecture document will be descriptions of the architecture and its subsequent views.
• View—The EATK provides eight common views for architecture descriptions that are common across most architecture efforts.
• Model—Models are fully supported in and incorporated into the system-architecture document.
• Environment—The 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:

• Rationale—The most important part of the architectural process is how we derive to our architecture 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 of considerations 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 content—An architecture schema that represents the information that we want to gather in our architecture document was created that has a viewpoint-based model applied to it.
• Qualifying information—Links between decisions that have been made and other systems or architecture 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 mechanisms—Provides facilities to store information from the schema, so that it can be related to other non-document–related information.
• Generating information—Provides a mechanism to rebuild or generate sections of an architecture document.

System-Architecture Markup XML

With an ontology and taxonomy for architecture, we now can look at what this means from an implementation perspective. The system-architecture document has an underlying XML structure that is 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 and rarely 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, not necessarily the structure itself.

The structure also shows how an architecture XML structure can be applied in a real-world architecture-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 entered into the system-architecture document will be stored here.

Figure 19. System-architecture XML file

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

1. Open Microsoft Office Word.
2. Click the Office button, and select New.
3. Click the system-architecture document template, and select Create.
4. Populate the document with your architecture descriptions.
5. Save the document to the desktop.
6. Go to the desktop, and change the extension of the document from .docx to .zip.
7. Double-click to open the document as a zip file. The file structure should be visible.
8. Double-click the Custom XML directory.
9. To open the XML file, double-click the item1.xml file.

The architecture XML file gives the system-architecture document a local data store that is carried along with the document. This opens up some interesting opportunities, when we look at how this can be used (see Figure 20).

Figure 20. item1.xml file

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 makers through 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 this implementation for architects.
• Architects can achieve significant productivity gains through reduction of manual activities and process automation.
• Architecture information can be used in a much more meaningful way by eliminating the 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 implementation—or, in some cases, replace it.
• Solutions such as COTS and custom-developed applications can be integrated with this solution through 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 for managing, delivering, and communicating the Microsoft position on enterprise architecture. He is responsible for driving Microsoft’s 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 infrastructure planning, portfolio management of technology projects, and solution architecture. As a thought leader, Mike combines this experience with a strong focus on strategic execution.

Visit Mike Walker’s blog: http://blogs.msdn.com/MikeWalker