Pragmatic Approach to Describing Solution Architectures

by Mike Walker

Summary: The return on investment of technical documentation is often not realized and documentation is frequently looked upon as a necessary evil. Creating the right architecture descriptions can help guide decision making at the various stages of the IT life cycle, however, there are limitations on formalized structures, information models, and intelligent tooling that takes the current architecture documentation to the next level of usefulness. In this article, we look at how we view, approach, and maintain architecture descriptions, and consider how this process can be improved.

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. 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.

This pervasive growth of documents shows how critical the information 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.

Figure 1: Documentation, increasing at an accelerated rate

As Figure 1 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 goal is to solve the deficiencies and challenges with current architecture documentation while preserving the aspects that do work and have been assimilated into the daily lives of architects.

To do this, we will explore the following concepts:

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.

Rethinking the Traditional Architecture Document

The most common and pervasive interface for creating architecture descriptions is Microsoft 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.

Figure 2: Microsoft Office Word reduces complexity and cost

As Figure 2 shows, Office provides a way to reduce complexity and costs significantly. The Office suite is easy to understand and most users already have them on their desktops. Augmenting the existing Office tools to make them fit the usage of architects is particularly ideal. It maintains a consumable amount of complexity while limiting the overall costs. 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

• Office PowerPoint

• Office Excel

• Office SharePoint

It is important to understand the context in which these tools interact.

Figure 3: Other productivity tools playing a role in the documentation process

Figure 3 shows an illustration of how other productivity tools play a part in architectural processes.

We can assert quickly that there is not just one tool that 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 in mind.

Optimizing Office Word to Describe Architectures

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 — Ability 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.

Through the use of the Office Word 2007 features that center on XML, we can truly start to extend this interface. Word does so by providing:

Embedding XML documents — embed XML file into document for full data qualification.
Office Word XML format — fully describes the formatting from the data through XML to have true separation of the formatting versus the information.
Content controls — map most content controls to elements in XML data attached to a document.

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.

The Architecture of the System-Architecture Document

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 metadata integration services.

For this solution, we will use a real world reference architecture called the Enterprise Architecture Toolkit (EATK). This toolkit will show how to alter Office Word from a word processor to a UI for describing architectures in a new way. 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 4: Architectural layers

As Figure 4 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-ofbusiness (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 5: Architecture behind EATK system-architecture document

Figure 5 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

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.

Tool Architecture

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.

Figure 6: Components of Office Word interface

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

Ribbons — We use this functionality as a launch pad for downstream activities, workflow triggering, collaboration, and information retrieval.
Task panes — 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

System-Architecture Document Ribbons

Using the ribbon for the system-architecture document, we will have a series of functions that relate directly to architectural processes and information. As Figure 7 shows, there are four ribbon components in the EATK:

Figure 7: Ribbon components of system-architecture document

Patterns Search — It displays patterns and existing IT assets that will help solve specific architecture-design questions and challenges.
Patterns Browser — 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 by integrating collaboration via office communication server (ocs)
Upload Doc — Automatically have a way to integrate architecture information into hosted workflow and consumed into a metadata repository.

System-Architecture Document 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. This information is not only visible, but also interactive.

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.

As one example of this is the Patterns Browser. The intent of the Patterns Browser is to surface pattern information into the design environment. Two types of information are displayed:

Assets — Shows what has been built.
Patterns — Shows what should be built.

As Figure 8 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.

Figure 8: Interacting with elements in document

Another innovative way the Task Pane is utilized is by introducing collaboration. The architectural process is no longer a onearchitect job. Typically multiple architects with specific roles design systems architecture. Examples of these roles include; Application, Information, Hardware, Security, or Infrastructure architect.

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.

Figure 9: Architect Lookup task pane

Architect Lookup would return the names and photos of the Hardware, Security, and Information architects. As Figure 9 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 metadata 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.

Figure 10: Collaborative architectures

Each role has a part to play in the architectural process. Given the illustration in Figure 10, 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 servertier 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?

Document-Template Architecture

Along with enhancements to the tool, the next layer of concern is the document 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 11 shows:

Figure 11: 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.

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.

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.

By using 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.

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 12: IEEE framework for architectural description

In Figure 12, 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 aspects that are implemented to support IEEE 1471 in the systemarchitecture 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.

The System Architecture Markup XML is a way to provide clear separation between the presentation markup and the information markup.

This greatly simplifies integration to hosted workflow, repositories, and third party tooling.

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.

About the Author

Mike Walker is a principle architect who delivers strategy for the enterprise architecture space at Microsoft. He is responsible for creating, driving, and evangelizing Microsoft’s worldwide Enterprise 2.0 and Enterprise Architecture strategies. Specifically, Mike ensures that institutions around the world realize the full extent of Microsoft’s vision and value proposition. He has also evolved many of the concepts behind mainstream architectural approaches and styles. His works are realized through publication in books, trade publications, authoritative architecture guidance, articles, code delivery and standardized frameworks. Those frameworks include: the Enterprise Architecture Toolkit (EATK), Loan Origination Reference Architecture, and Financial Services Component Library. You can visit his blog at http://www.MikeTheArchitect.com

Follow up on this topic

Advertise Here