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