A key part of the software architect's job is producing an architectural description of the system that defines the architecture's key functions, features, and characteristics for its stakeholders. Where do you start? What do you need to know? Nick Rozanski and Eóin Woods provide detailed answers to these questions, with useful suggestions on how to attack this fundamental document that underpins any development project.

From the author of

The practice of architecture has a solid theoretical foundation that goes
back at least to Roman times, when Marcus Vitruvius Pollio wrote the first-ever
architectural handbook, de Architectura libri decem—"Ten
Books on Architecture." Vitruvius described the architect's role and
required skills and provided a wealth of material on standard architectural
structures. Over the next 2,000 years, this definition was refined, extended,
and underpinned by a solid theoretical, practical, and regulatory framework that
today guides the work of every architect.

Unfortunately, everything in the previous paragraph refers to
building architects. The position of the software systems architect is
scarcely comparable to that of our counterparts in construction. We work in an
industry, information and communications technology, which is scarcely over 50
years old, and it wasn't until the 1990s that we seriously started to think
about how the elements of a computer system fit together into a coherent
whole—the system's architecture.

While it's rare today for a large systems development project not to
include at least one architect, and many organizations have a whole department
responsible for developing architectural strategy and vision for the enterprise,
there is very little consensus over what the job actually involves:

Who are our clients?

To whom are we accountable?

What are we expected to deliver?

What is our involvement once the architectural design has been
completed?

Where are the boundaries between requirements, architecture, and
design?

This situation makes things very difficult for the newly appointed architect
and causes problems even for the more experienced architect. It also confuses
our colleagues, our management, and the other people with whom we work.

If you've read the standard books on software systems architecture, you
know that a key part of your job is to produce an architectural
description (AD) of your system. The AD documents your architecture in a
way that people can understand, and helps to demonstrate that the architecture
has met their concerns. Your developers will use it to guide their design and
coding work (they're certainly going to blame you if something doesn't
work), and many other people are going to be interested in it.

What the books don't really tell you is how you should go about
producing your AD. Where do you start? Who do you talk to? What do you put into
it? What can you safely leave out? How do you validate it and get it signed off?
There are no simple answers to these questions, but you have a much greater
chance of success if you focus your attention on three activities:

Identifying your stakeholders and working with them to create an
architecture that meets their complex, overlapping, and often conflicting
needs

Using views and viewpoints to help you define and document
the structure of your architecture, making what is a huge problem
manageable

Using perspectives to help understand the "quality
properties" of your system—such as performance, availability, and
security—and to ensure that your system meets its nonfunctional goals

Let's look at each of these activities in a bit more detail.

Identifying and Engaging Your Stakeholders

Traditional software development has been driven by the need of the delivered
software to meet the requirements of users. However, the people affected by a
software system are not limited to those who use it. That is, software systems
are not just used: They have to be built and tested, they have
to be operated, they may have to be repaired, they are usually
enhanced, and of course they have to be paid for.

Each of these activities involves a (possibly significant) number of people
in addition to the users. Each of these groups of people has its own
requirements, interests, and needs to be met by the software system. We refer to
these people collectively as stakeholders.

IEEE Standard 1471-2000 defines a stakeholder in a software architecture as a
person, group, or entity with an interest in or concerns about the realization
of the architecture. Stakeholders (explicitly or implicitly) drive the whole
shape and direction of the architecture, which is developed solely for their
benefit and to serve their needs. Stakeholders ultimately make or direct the
fundamental decisions about scope, functionality, operational characteristics,
and structure of the eventual product or system—under the guidance of the
architect, of course. Without stakeholders, there would be no point in
developing the architecture because there would be no need for the system it
will turn into, nor would there be anyone to build it, deploy it, run it, or pay
for it.

Architectures are created solely to meet stakeholder needs. A good
architecture is one that meets the objectives, goals, and needs of its
stakeholders. It follows that if a system doesn't meet the needs of its
stakeholders, it can't be considered a success—no matter how well it
conforms to good architectural practice. In other words, architectures must be
evaluated with respect to stakeholder needs as well as abstract architectural
principles.

Draw up and review the list of key business and technology
stakeholders.

Brief the stakeholders individually or in groups to explain your role and
make sure that they understand what's required of them.

Review the system scope with stakeholders and document it in a context
diagram.

Regularly review the AD with stakeholders and refine it to reflect their
comments.

Our use of the term concern here is particularly appropriate to the
process of architecture. You're engaged in a process of discovery as much
as one of capture—in other words, this early in the system development
lifecycle, your stakeholders may not yet know their precise requirements. Many
concerns will be common among stakeholders, but some concerns will be distinct
and may even conflict. Resolving such conflicts in a way that leaves
stakeholders satisfied can be a significant challenge.

Some stakeholders are more interested in their roles than others, for a
variety of reasons, and few have a clear idea of what they're expected to
do. Part of your role is to engage and galvanize, to persuade people of the
importance of their involvement, and to obtain their commitment to the task.