Share via


Architecture: Description Really Matters


Yan Zhao, PhD

May 2007

Summary: Architecture description can affect the "life and death" of the software system that it describes. (6 printed pages)


Establishing Vision and Insight
Identifying Architecture Scope and Audience
Critical-Thinking Questions
Further Study


Many years ago, I was hired as a corporate-level principal architect. The first assignment I got was to describe the architecture of an existing software-system product inherited from a company acquisition. The people who created the system originally had left the company. There were no architecture or design documents; no one had insight about it to be able to describe what it really was. Folks did not know how to market it to external customers, so the product faced the "death penalty." To the engineering teams who understood something of the system, however, the product was current, state-of-the-art, and very competitive, with lots of great ideas built-in. By collecting information from multiple channels, I provided the architecture description for this system, and did it justice. Also, I provided an architecture for its future evolution. Both marketing folks and engineering teams were happy with the results.

By sharing my experience, I will show what is involved with creating an architecture description, and how we architects can perform our roles effectively. In the context of overall architecture design, the goal of creating an architecture description is to transform the collected and organized architectural information and intents into viable models. The creation and adoption of effective architecture approaches, methodologies, patterns, reference models, and so on can certainly benefit architecture description. The architecture description is the end product of an architecture-development process, and it is the ultimately visible representation of architecture. Let's look at more details in the following subsections.

Establishing Vision and Insight

To provide construction guidance, as well as to support marketing in fulfilling potential customer needs, architecture has to have vision and insight—both of which are crucial for product success.

For my architecture-description assignment mentioned earlier, the first thing I did was to understand the purpose of the system, its goal, and possible usage scenarios. I did feel pressure at the beginning, as a new person in the company; I was not sure if my review and description document could make both marketing and engineering happy. I decided to take a forward-looking approach, based on what I had learned of the system's purpose and goals. Then, I performed detailed product studies with help from the engineering team. I tried to line-up their current product with clear future vision and insight. By doing that, I was able to bring both marketing and engineering folks together onto a common page for moving forward.

Architecture is a creative art, even if it is based on an existing legacy system. It is not only for engineering or construction guidance, but it also has to provide insight, intent, and vision, so that it can guide the system in moving forward through continual evolution.

Identifying Architecture Scope and Audience

To make the architecture-description content effective and well-accepted, we must identify the scope of our architecture coverage and the intended audience, so that we can cover the right material to meet peoples' interests and backgrounds.

For this architecture-description assignment, my audiences clearly included marketing and engineering, as well as management. The scope of my architecture description had to incorporate the interests of all the involved parties, and had to be able to answer their questions from different perspectives. To achieve that, I planned my architecture content to cover different levels and aspects in different sections, with the common high-level content at the beginning.

To support my content, I decided to create a couple of diagrams to describe the concept of the software-system operations and its associated application scenarios, for both "as-is" and "to-be" products. This approach did help in bringing people from different roles together to have a common understanding about the software product.

A successful architecture description has to consider myriad backgrounds, to determine the scope that the architecture should cover. You have to be able to describe your concepts to different audiences, such as customers, sales and marketing folks, management, and engineering teams, so that you can get buy-ins, support, and funding, and get it implemented to achieve real value.


Information-gathering is a critical step for the creation of architecture. The information quality and coverage will affect the accuracy of architecture description.

For the assignment mentioned earlier, after the architecture-description content strategy was decided upon, based on scope and audience, the next step for me was to perform information collection, analysis, synthesizing, and modeling. This was an iterative process. The token steps included:

  1. Identifying interviewees.
  2. Communicating architectural intent, concepts, and activities to the interviewees and relevant people.
  3. Conducting interviews and collecting information from multiple channels—for example, conversation, segments of design documents, e-mails, and meeting minutes.
  4. Synthesizing and conceptualizing the information, and organizing it into models and documents.
  5. Conducting reviews with relevant people, and further improving and extending the architectural-model descriptions.

Effective information collection and synthesizing are very important in establishing a foundation and baseline for architecture description. The architecture is more easily accepted by stakeholders if it reflects their views.

Models and Views of Architecture Creation

In the information-gathering steps described in the last section, we mentioned architecture modeling in the last two steps that were performed iteratively with information gathering and synthesizing processes. For architecture modeling, we must select an architecture style, identify architecture principles (or constraints), and determine views for the presentation of architecture models. The models and views are the core of an architecture description.

Based on my experience in the Common Object Request Broker Architecture (CORBA) and object-oriented paradigms, I selected component-based and service-oriented architecture (SOA) styles, which suited the existing Java-based development environment very well. I started with some conceptual diagrams of the software-system operations, which helped in establishing common understanding. Figure 1 illustrates an example.


Figure 1. The concept-of-operation diagram for a software system

The component-based architecture for the software system was based on the diagrams of the concept of operations. The operational components were mapped and decomposed to implementable software components. Figure 2 illustrates the components and their interoperation relationships.


Figure 2. A component-relationship diagram for component-based software architecture

Software architecture is the structure, or structures, of the system that comprise software components, the externally visible properties of those components, and the relationships between them [Bass et al. 1998]. The term structure means a model or view of a system. Components are the architectural objects in each of these views.

For current practice, some standard architecture-description languages can be considered also, although they are not in the scope of this article. These are terms such as architecture-description language (ADL) and architecture-description markup language (ADML). Information on these is widely available.

Competitive Analysis and Technology Options

In response to marketing requests for a software product, competitive analysis of the market was necessary. To support my architecture vision and views, I summarized major competitive products in the landscape with an analysis of their pros and cons, both in features and in technical implementations. Based on that competitive analysis, our product position was justified.

If competitive analysis is to make marketing folks comfortable, the technology options for the described architecture are to convince and provide guidance for the engineering teams in actual product implementation. In the architecture-description document, what I included were options for platforms and development tools, technology standards, available commercial off-the-shelf (COTS) products, and so on. I also mapped the logical architecture to the physical architecture—in terms of implementable software components—by using selected technologies and COTS products, which the engineering teams liked to see.

A good architecture description should provide a viable position for marketing, as well as clear guidance for engineers to implement the design, based on the current state-of-the-art technology.

Road Map for Engineering

We all know that software products go through versions. It is impossible to implement all the features at once. Therefore, product development is also an iterative process, with a phased product life cycle. With considerations in changing requirements from market, technology advancement, architecture dependencies, available budget, and other possible factors, a road map for engineering will provide guidance on which feature or software component will be implemented first, and which will be implemented next, or later on.

I provided an engineering road map in my description of architecture, which was crafted based upon current product and direction. It prioritized the extension components based on marketing requirements, technical viability, component's mutual dependencies, cost, and other factors. The road map was also a tool that brought different parties onto the same page and set compatible expectations for them in playing their roles upon moving forward.

A good architect should be able to create a road map for engineering, based on the architecture that is created. The road map should reflect the architect's insight and vision, as well as knowledge in component dependencies, technology availabilities, marketing priorities, and so on.


For construction—regardless of whether it is a building or a computer software system—the architecture description is critical for success. It expresses a creative art in terms of insight, vision, usage scenarios, structural models, processes, technology options for implementation, and so on. Software architecture is a live conceptual art; it has its own life cycle in inception, creation, updates, and maintenance. Its insight, intent, vision, and models can guide the software implementation moving forward through continuous evolutions.

The effectiveness of architecture description has to consider multiple aspects:

  • The considerations of purpose, scope, and audience are helpful for its guiding position, as well as for its acceptance and buy-in.
  • Effective information collection and synthesizing are important in establishing a baseline for architecture description. The architecture will be more easily accepted by stakeholders if it reflects their views.
  • We have to create different models and views for the same concepts to suit people in different roles, responsibilities, and backgrounds.
  • Market analysis, technology options, and implementation road maps are helpful in bringing architecture to reality in an iterative and phased manner.

Critical-Thinking Questions

The following are some critical-thinking questions that architects should think about before getting into architecture description:

  • What is the scope of the architecture?
  • Who are the intended audiences for the architecture description?
  • What architecture style should be used for architecture description?
  • What approaches and methodologies should be adopted?
  • Are there any helpful tools?


  • [Bass et al. 1998] Bass, Len, Paul Clements, and Rick Kazman. Software Architecture in Practice. Reading, MA: Addison-Wesley, 1998.

Further Study


About the author

Dr. Yan Zhao works for CGI Federal as Director for Enterprise and Solutions Architecture. She has extensive work experience in academia, corporate research, software industry, and consulting services, with 11 years of architectural-leadership experience in IT strategic planning, enterprise and system architecture, software architecture, enterprise system modernization, and various technology solutions. She has five patents granted and four patents pending, and holds a PhD in computer science. She can be reached at

This article was published in Skyscrapr, an online resource provided by Microsoft. To learn more about architecture and the architectural perspective, please visit