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.aspx8/2/2019 Pragmatic Approach to Describing Solution Architectures
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
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://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.aspx8/2/2019 Pragmatic Approach to Describing Solution Architectures
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
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://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.aspx8/2/2019 Pragmatic Approach to Describing Solution Architectures
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.
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://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.aspx8/2/2019 Pragmatic Approach to Describing Solution Architectures
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.
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://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.aspx8/2/2019 Pragmatic Approach to Describing Solution Architectures
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
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://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.aspx8/2/2019 Pragmatic Approach to Describing Solution Architectures
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.
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://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.aspx8/2/2019 Pragmatic Approach to Describing Solution Architectures
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
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://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.aspx8/2/2019 Pragmatic Approach to Describing Solution Architectures
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
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.aspx8/2/2019 Pragmatic Approach to Describing Solution Architectures
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.
gmatic Approach to Describing Solution Architectures http://msdn.microsoft.com/en-us/library/dd451087.asp
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.aspx8/2/2019 Pragmatic Approach to Describing Solution Architectures
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
gmatic Approach to Describing Solution Architectures http://msdn.microsoft.com/en-us/library/dd451087.asp
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.aspx8/2/2019 Pragmatic Approach to Describing Solution Architectures
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
gmatic Approach to Describing Solution Architectures http://msdn.microsoft.com/en-us/library/dd451087.asp
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://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.aspx8/2/2019 Pragmatic Approach to Describing Solution Architectures
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:
gmatic Approach to Describing Solution Architectures http://msdn.microsoft.com/en-us/library/dd451087.asp
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://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.aspx8/2/2019 Pragmatic Approach to Describing Solution Architectures
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.
gmatic Approach to Describing Solution Architectures http://msdn.microsoft.com/en-us/library/dd451087.asp
f 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.aspx8/2/2019 Pragmatic Approach to Describing Solution Architectures
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.
gmatic Approach to Describing Solution Architectures http://msdn.microsoft.com/en-us/library/dd451087.asp
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.aspx8/2/2019 Pragmatic Approach to Describing Solution Architectures
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.
gmatic Approach to Describing Solution Architectures http://msdn.microsoft.com/en-us/library/dd451087.asp
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.aspx8/2/2019 Pragmatic Approach to Describing Solution Architectures
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
gmatic Approach to Describing Solution Architectures http://msdn.microsoft.com/en-us/library/dd451087.asp
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.aspx8/2/2019 Pragmatic Approach to Describing Solution Architectures
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
gmatic Approach to Describing Solution Architectures http://msdn.microsoft.com/en-us/library/dd451087.asp
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://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.aspx8/2/2019 Pragmatic Approach to Describing Solution Architectures
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
gmatic Approach to Describing Solution Architectures http://msdn.microsoft.com/en-us/library/dd451087.asp
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://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.aspx8/2/2019 Pragmatic Approach to Describing Solution Architectures
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.
gmatic Approach to Describing Solution Architectures http://msdn.microsoft.com/en-us/library/dd451087.asp
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://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.aspx8/2/2019 Pragmatic Approach to Describing Solution Architectures
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.
gmatic Approach to Describing Solution Architectures http://msdn.microsoft.com/en-us/library/dd451087.asp
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://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.aspx8/2/2019 Pragmatic Approach to Describing Solution Architectures
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).
gmatic Approach to Describing Solution Architectures http://msdn.microsoft.com/en-us/library/dd451087.asp
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://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.aspx8/2/2019 Pragmatic Approach to Describing Solution Architectures
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
gmatic Approach to Describing Solution Architectures http://msdn.microsoft.com/en-us/library/dd451087.asp
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.aspx8/2/2019 Pragmatic Approach to Describing Solution Architectures
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
gmatic Approach to Describing Solution Architectures http://msdn.microsoft.com/en-us/library/dd451087.asp
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/EATop Related