On documenting Software Architectures (for Business Applications)

Read this article if you want to learn how Software Architectures can be documented. A multitude of tools, diagrams, thoughts and instructions can be found via the Internet. Often the “how” is put in before the “why” and “what”. In this article I want to address “which” artifacts you absolutely need to think about and “why”. Because the development of Software Architectures is not about tools and diagrams: it is about how the architecture can be documented – and presented – most efficiently as well as effectively.

1.      Abstract

The development of Software Architecture is to some degree a creative process but relies as well on software engineering principles, best practices and lessons learned.

This article briefly outlines the primary architectural artifacts encountered in business application development projects. The aim is to give guidance on how Software Architecture can be defined, and in particular, documented.

The list of artifacts provided is by no means complete or definite, but is a list of artifacts that provide value to every business application development project, such as: non-functional requirements, architectural decision log, architecture overview, component-, data- and deployment-models, and architectural design documents.

If it is deemed necessary by the project it can easily be extended with additional artifacts that document an aspect that is not been covered by this article.

The methodological aspect, while very important in software development projects, is going to be covered by a different article.

2.      Introduction

How Software Architecture is documented depends on the purpose of the Architecture that has been developed. Examples are: Reference Architectures, Architectures for specific Software Systems, and others. Due to the aim of this blog I focused on Business Applications in order to be able to be more precise.

Documenting Software Architecture fulfills two important purposes:

  • It serves as a vehicle for communication in that it helps communicating the architecture to different levels of the client organization, and
  • Is the baseline for validating the Architecture against those requirements that formed it.

This defines the primary focus of the development effort. Quantity does not count. It is much more important that the Architecture contains the right elements; those that define the critical aspects of the Architecture and its implementation.

While a particular notation can be useful and necessary in some circumstances it is not the key factor. Again, it is much more important to focus on defining the right things than on the notation used.

What I am trying to focus on in this article is to provide a list of artifacts that are most commonly found in the definition of Software Architectures and represent in my point of view the necessary minimum. If it is not complete in a particular context it can easily be extended with additional ones.

The Software Architecture that has been developed can be viewed as a model. Not a model in the sense of a single, for example UML, model but in the sense of a consistent model of the software that will be developed. Hence, documenting the Software Architecture can be looked upon as developing different views of that model.

3.      The elements of documentation

There is, based on my experience, a core set of documents that are required to define a Software Architecture. This ensures that every important – basic – aspect of the constructed architecture is covered.

The Software Architecture lays out the principle design characteristics of a system. It defines the “how”, as opposed to the “what” which is defined by the requirements. The development of a Software Architecture will, at the minimum, require the following activities to be performed:

  • Define a basic Architecture is defined based on non functional and, in some instances, functional requirements,
  • Group the system into functional components,
  • Decompose the system into technical tiers, layers, components,
  • Model the system’s data,
  • Evaluate and define the context the system is embedded into,
  • Build a conceptual user interface and design guidelines,
  • Address the deployment- and operational aspects of the system,
  • Capture all design decisions and create the master design

The primary purpose of the Architecture developed – and documented – is to bridge the gap between the business’ needs and the technical solution for that need. The artifacts of architectural documentation are developed collectively in an iterative manner, moving them from a conceptual to a logical and finally to a physical level.

The most common elements of architecture documentation
Figure 1 - The most common elements of architecture documentation
Non-Functional and Functional Requirements, Givens and Constraints

Requirements form the input for the Architecture. Primarily it will be the givens, constraints, and non-functional requirements that shape the Architecture. For additional information on working with requirements see also [Pic2010]. Requirements are provided by the client or sponsor or developed by the Architect based on input by the sponsor.

Requirements are often documented using word processors or by using the help of a requirements management tool.

An example of a non-functional requirement is: “The application must provide a Windows-based user interface.”

Log of Architectural Decisions

The log of architectural design decisions is shown at the bottom of the figure because it is a central element. This artifact evolves continuously throughout the project. The significance of it is that it consciously and comprehensively documents the architectural design decisions made.

Typically I create and maintain this artifact using a word processor.

Example for an architectural decision: “The application is going to have a Windows-based user interface as opposed to a Web-based user interface because the target audience is back-office users.”

Architectural Overview

The Architecture Overview is a summary of the Architecture constructed and the most important decisions faced. It is an important aid in communicating the Architecture to various levels of the project- and management in the stakeholder organization.

The Architecture Overview is supposed to be a bright and colored storybook telling the story of the Architecture in the levels of detail necessary for the audience. Typically I do it using slides and sometimes create summaries using a word processor.

Modeling the Components

This is a modeling activity that is at the very core of the Architecture. This is where the black-box of a future system is decomposed into its individual components, such as technical and functional components. It shows and demonstrates how those components relate to and work with each other.

For me, the most convenient notations for this kind of work are UML component diagrams [Amb2009a], layer diagrams [CMUSEI2010c] and textual descriptions.

Modeling Services

In today’s IT environments it is often a requirement that applications offer a service interface. Services are not merely a low level API for distributed components, but a means of integration on the process layer and therefore require a specialized design model focussing on those aspects.

How you document the service design depends on the purpose. Most useful seems to me to do the identification and selection using a spreadsheet. The functional behaviour of services is best described using Use Cases in a word processor.

Modeling the Data

Modeling data is sometimes treated like a stepchild of Architecture. In Software Architectures I often limit my understanding of data to the primary logical entities of data. Two views of data are relevant:

  • A high level logical data model is sufficient to gain an understanding of the data the application deals with. A more detailed logical data model will be developed in the analysis cycle of the project or component.
  • Representative data components in the component diagrams in order to connect the functional and technical architecture to data.

Do not confuse modeling data with Data Architecture which is required in some applications that have significant non-functional requirements around handling data. For example applications that have rigorous requirements on reporting, or distribution of data.

The data model is done best with a data modeling tool using EER notation.

Modeling the Context

This element accounts for the fact that software applications are embedded into an existing network of applications. This can range from simply exchanging data to being tightly integrated from a process point of view. This activity is about identifying, cataloging and characterizing all interfaces the software system will have to other applications.

I usually do this by drawing a system context diagram [Wikipedia2010] alongside a textual characterization of each interface.

Documenting the Architectural Design

Requirements are refined clustered iteratively around characteristics as outlined in [Pic2010]. This activity creates master-designs for all critical aspects of the architecture. It explains those aspects that can not be conveyed with the diagrams.

I usually do this with a word processor. The individual design documents describe the design, and capture the decisions and the rationale.

Modeling Deployment and Operational Aspects

This activity models the deployment and operational aspects for the software developed. Those are often related to infrastructure, hardware, load & capacity profiles, software packaging, deployment locations, and walk-through diagrams. The activity is usually not started right at the beginning of a project.

I usually do this with the help of a charting tool drawing network- [Amb2009b] and walkthrough diagrams. When necessary it is accompanied by prose. I have found UML deployment diagrams too restrictive and limiting at the same for that purpose.

Defining the User Interface

Last but not least I wanted to mention the user interface. It is helpful to define common user interface standards early on in the project in order to gather requirements about usability, behaviour and style, set a baseline as well as a standard for the development team.

Often those conceptual user interface models are done using graphical tools or sometimes by building a prototype.

4.      Conclusion

All this builds the technical basis for the Software Architecture. It may sound a lot but isn’t in reality. It is up to the Architect to keep it to the necessary but meaningful minimum.

The Architecture is not the only but an important input for all activities in a project. It is particularly important for planning and design. Sometimes not recognized, the Functional Architecture will also be a valuable input for structuring and planning the analysis work.

The list of artifacts outlined in this article is not a complete list, but it a list of artifacts I typically see in business application development. What is exactly needed depends most on the kind of application developed.

An important area, briefly touched in [Pic2010], is the development process of Architecture itself. This raises specific questions such as how Architecture work fits into the overall software development process, how it impacts and is impacted by the development methodology as well as qualitative aspects of software.


[Amb2009a] Ambler, S. 2009, “UML 2 Component Diagrams”, Agile Modeling (AM) Home Page [online] available at http://www.agilemodeling.com/artifacts/componentDiagram.htm

[Amb2009b] Ambler, S. 2009, “Network Diagrams”, Agile Modeling (AM) Homepage [online] available at http://www.agilemodeling.com/artifacts/networkDiagram.htm

[Amb2009c] Ambler, S. 2009, “UML 2 Deployment Diagrams”, Agile Modeling (AM) Homepage [online] available at http://www.agilemodeling.com/artifacts/deploymentDiagram.htm

[Ars2004] Arsanjani, A. 2004, “Service-oriented modeling and architecture”, IBM developerWorks [online] available at http://www.ibm.com/developerworks/library/ws-soa-design1/

[BerPauKazRud2009] Berenbach, B., Paulish, D. J., Kazmeier J., Rudorfer, A. 2009, Software & Systems Requirements Engineering: In Practice, McGraw-Hill/Osborne, New York

[Bre2003] Bredemeyer Consulting. 2003, “Software Architecture Documentation”, Software Architecture, Architects and Architecting [online] available at http://www.bredemeyer.com/architecture_documentation_action_guides.htm

[CMUSEI2010a] Software Engineering Institute. 2010, “Community Software Architecture Definitions”, Carnegie Mellon University [online] available at http://www.sei.cmu.edu/architecture/start/community.cfm

[CMUSEI2010b] Software Engineering Institute. 2010, “Software Archtiecture Overview”, Carnegie Mellon University [online] available at http://www.sei.cmu.edu/architecture/

[CMUSEI2010c] Software Engineering Institute. 2010, “Software Architecture Documentation in Practice: Documenting Architectural Layers”, Carnegie Mellon University [online] draft available at http://www.sei.cmu.edu/library/abstracts/reports/00sr004.cfm

[Fir2009] Firesmith, D. G. 2009, The Method Framework for Engineering System Architectures, Auerbach Publications, Boca Raton

[ForGilPurMoe2008] Ford, C., Gileadi, I., Purba, S., & Moerman, M. 2008, Patterns for Performance and Operability: Building and Testing Enterprise Software, Auerbach Publications, Boca Raton

[Gal2007], Galitz, W. O. 2007, The Essential Guide to User Interface Design—An Introduction to GUI Design Principles and Techniques, Third Edition, John Wiley & Sons, Indianapolis

[Gar2003], Garland, J., Anthony, R. 2003, „Large-Scale Software Architecture: A Practical Guide using UML”, John Wiley & Sons

[Gor2006] Gorton, I. 2006, Essential Software Architecture, Springer, Garden St Eveleigh

[Gra2008] Graham, I. 2008, Requirements Modelling and Specification for Service Oriented Architecture, John Wiley & Sons, Indianapolis

[Lat2009] Lattanze, A. J. 2009, Architecting Software Intensive Systems: A Practitioners Guide, Auerbach Publications, Boca Raton

[SimWit2005] Simsion, G. C., Witt, G. C. 2005, Data Modeling Essentials, Third Edition, Morgan Kaufmann Publishers, Burlington

[Pic2010] Pichler, M. 2010, “Introduction into the Development of Software Architectures”, Documentation of Software Architectures [online] available at https://applicationarchitecture.wordpress.com/2010/01/19/introduction-into-the-development-of-software-architectures/

[Pen2003] Pender, T. 2003, UML Bible, John Wiley & Sons, Indianapolis

[Spo2001] Spolsky, J. 2001, User Interface Design for Programmers, Apress, Berkeley

[Tia2009] Tiako, P. 2009, Designing Software-Intensive Systems—Methods and Principles, IGI Global, Hershey

[Vli2008] Vliet, H. v. 2008, Software Engineering—Principles and Practice, Third Edition, John Wiley & Sons, Indianapolis

[Wei2007] Weilkiens, T. 2007, Systems Engineering with SysML/UML—Modeling, Analysis, Design, Morgan Kaufmann Publishers, Burlington

[Wikipedia2010] Wikipedia. 2010, “System context diagram”, Wikipedia [online] available at http://en.wikipedia.org/wiki/System_context_diagram

Copyright © 2010 Michael Pichler


3 thoughts on “On documenting Software Architectures (for Business Applications)

  1. I have changed the title from “How to document Software Architectures” to “On documenting Software Architectures” because the post doesn’t describe the only way, but my thoughts on documenting architectures. Concepts I have come to think of as valuable.


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s