Software Design And Architecture

Presentation Topic:
Documenting Software Architecture

Represented by:
Saba Naaz
CMS # 249
Jeveria Qurat-Ul-Ain
CMS#252
Documenting Software Architecture

Software Architecture:
The software architecture of a program or computing
system is the structure or structures of the system, which
compromise the software elements, the externally visible
properties of those elements, and the relationship among
them.
Documenting Software Architecture

Introduction:
 The architecture serve as a basic for both a system and the project
developing it.

 It defines the work assignments that must be carried out by design and
implementation teams and it is the primary carrier of system qualities
such as performance, modifiability and security-----None of which can
be achieved without a unifying architectural vision.

 Architecture is an articraft for early analysis to sure that design

approach will yield an acceptable system.
Documenting Software Architecture
 Documenting the architecture is the crowning step to crafting it.

 Even a perfect architecture is useless if no one understands it.

 If you go to the trouble of creating a strong architecture you must

describe it in sufficient detail, without ambiguity and organized in such
a way that others can quickly found the needed information.
Documenting Software Architecture
USES
 The architecture for a system depends on the requirements levied on it.

 Documentation is decidely not a case of “one size fits all”, it should be sufficiently
detailed to serve as a blueprint for analysis.

 Architecture documentation is both prescriptive or descriptive. That is for some

audiences it prescribes what should be true by placing constraints on decisions to
be made. For other audience it describes what is true by recounting decisions
already made about a system’s design.

 All of this tells us that different stakeholders for the documentation have different
needs , different kinds of information, and different treatment of information.
Documenting Software Architecture

 One of the most fundamental rules for technical documentation in

general and software architecture documentation in particular, is to
write from the point of view of the reader.

 Documentation that was easy to write but is not easy to read will not be
used, and “easy to read” is in the eye of the beholder or in this case the
stakeholder.
Documenting Software Architecture

Views:
 We define a software architecture for a system as “The software
architecture of a program or computing system is the structure or
structures of the system, which compromise the software elements, the
externally visible properties of those elements, and the relationship
among them.” And we said that a view is a representation of a coherent
set of architectural elements, as written by and read by system
stakeholders. A structure is the set of elements itself, as they exist in
software or hardware.
Documenting Software Architecture

 The concept of view, which you can think of as capturing a structure,

provides us with the basic principle of documenting software
architecture:

“Documenting an architecture is a matter of documenting a

relevant views and then adding documentation that applies to more
than one view.”
Documenting Software Architecture

Choosing relevant views:

 Different views support different goals and uses.
 The views you should document depends on the uses you expect to
make of the documentation.
 Different views will highlight different system elements and/or
relationship.
Documenting Software Architecture

Documenting a view:
 There is no industry standard template for documenting a view, but the seven
part standard organization that we suggest in this section has worked well in
practice.

 First of all whatever sections you choose to include, make sure to have a
standard organization. Allocating specific information to specific sections will
help the documentation writer attack the task and recognize completion, and it
will help the documentation reader quickly find information of interest at the
moment and skip every thing else.
Documenting Software Architecture
Documenting a view

1. Primary presentation shows the elements and the relationship among

them that populate the view.

The primary presentation should contain the information you wish to

convey about the system first. It should certainly include primary
elements and relations of the views, but under some circumstances it
might not include all of them.

For example you may wish to show the elements and relations that come
into play during normal operation, but relegate error handling or
exceptional processing to the supporting documentation.
Documenting Software Architecture
Documenting a view

2. Element catalog details those elements and relations depicted in the

primary presentation, and perhaps others. Producing the primary
presentation is often what architect concentrates on, but without
backup information that explains a picture, it is of little value.

3. Context diagram shows how the system depends in the view relates
to its environment in the vocabulary of the view.
Documenting Software Architecture
Documenting a view

4. Variability guide shows how to exercise any variation points that

are a part of the architecture shown in this view. In some
architectures, decisions are left unbound until a later stage of the
development process, and yet the architecture must still be
documented.

5. Architecture background explains why the design reflected in the

view came to be. The goal of this section is to explain someone why
the design is as it is.
Documenting Software Architecture
Documenting a view

6. Glossary of terms used in the views, with a brief description of

each.

7. Other information: The precise contents of this section will vary

according to the standard practices of your organization. They might
include management information such as authorship, configuration
control data and change histories.
Documenting Software Architecture
Documenting Behavior:

 Views present structural information about the system.

 However, structural information is not sufficient to allow reasoning about some

system properties.

 Reasoning about deadlock, for example, depends on understanding the sequence

of interactions among the elements and structural information alone does not
present this sequencing information.

 Behavior description add information that reveals the ordering of interaction

among the elements.
Documenting Software Architecture
Documenting Behavior

 Behavior can be documented either about an element or about an

ensemble of elements working in concert.

 Exactly, what to model depend on the type of system being designed .

Documenting Software Architecture

Documenting interfaces:

 An interface is a boundary across which two independent entities meet

and interact or communicate with each other.

 Documenting an interface consists of naming and identifying it and

documenting its syntactic and semantic information.

 An interface is documented with an interface specification, which is a

statement of element properties the architect chooses to make known.
Documenting Software Architecture

A Template for Documenting interfaces:

Here is a suggested standard organization for interface documentation.

1. Interface identity: When an element has multiple interfaces, identify the individual
interfaces to distinguish them. This usually mean naming them.

2. Resources provided: The heart of an interface document is the resources that the
element provides. Define them by giving their syntax, their semantics and any
restriction on their usage.
 Resource syntax: This is the resource’s signature. The signature includes
any information another program will need to write a syntactically correct
program that uses the resource.
Documenting Software Architecture
A Template for Documenting interfaces

 Resource semantics: this describes the result of invoking the resource. It might
include
 Assignment of values of data that the actor invoking the resource can access. It
might be as simple as setting the value of return argument or as far reaching as
updating a central database.
 Events that will be signaled or messages that will be sent as result of using the
resource.
 How other resource will behave in the future as the result of using this resource.

In addition, the statement of semantic should make it clear whether the resource
execution will be atomic or may be suspended or interrupted. The most
widespread notation for conveying semantic information is natural language.
Documenting Software Architecture
A Template for Documenting interfaces

3. Data type definition: if any interface resources employ a data type

other than one provided by the underlying programming language,
the architect needs to communicate the definition of that data type.

4. Exception definitions: These describes exceptions that can be raised

by the resources on the interface.

5. Variability provided by the interface: Does the interface allow the

element to be configured in some way?
Documenting Software Architecture
A Template for Documenting interfaces

6. Quality attribute characteristics of the interface: The architect needs to

document what quality attribute characteristics the interface makes known to
the element’s users.

7. Element requirements: What the element requires may be specific named

resources provided by other elements.

8. Rationale and design issues: As with rationale for the architecture at large,
the architect should record the reasons for an element’s interface design.
Documenting Software Architecture

Documentation across views:

cross view documentation consists of just three major aspects:
1. How the documentation is laid out and organized ?

2. What the architecture is?

3. Why the architecture is the way it is?

Documenting Software Architecture
Documentation across views

How the document is organized

1.1 View catalog
1.2 View template
Why the Architecture is:
2.1 System overview
2.2 Mapping between views
2.4 Project glossary
Why the architecture is the way it is:
3.1 Rationale
Documenting Software Architecture

How the documentation is organized

View Catalog:
 A view catalog is reader’s introduction to the views that the architect has chosen to
include in the suite of documentation.

 There is one entry in the view catalog for each view given in the documentation
suite. Each entry should give the following:

1. The name of the view and what style is instantiates

2. A description of the view’s element types, relation types, and properties
3. A description for what the view is for
4. Management information about the view document, such as latest version.
Documenting Software Architecture
How the documentation is organized

View Template:
 A view template is the standard organization for a view.

 It helps a reader to navigate quickly to a section of interest.

 It helps a writer organize the information and establish criteria for knowing
how much work is left to do.
Documenting Software Architecture

What The Architecture Is

This section provides the information about the system whose architecture is
being documented, the relation of the views to each other, and an index of
architectural elements.
System Overview:
This is short prose description what the system’s function is, who its users are
and any important background and constraints.
Mapping between views:
Since all of the views of an architecture describe the same system, it stands to
reason that any two views will have much in common.
Documenting Software Architecture
What The Architecture Is

Element List:
The element list is simply an index of all of the elements that appear in any
of the views, along with a pointer to where each one is defined.

Project Glossary:
The glossary lists and defines terms unique to the system that have special
meaning. A list acronyms and the meaning of each, will also be appreciated
by stake holders.
Documenting Software Architecture

Why The architecture is the way it is: Rationale

It explains why a decision was made and what the implications are in
changing it.
Documenting Software Architecture

Conclusion:
An architecture is worthless if nobody can understand what it is or how
to use it. Use the stakeholder to help chose the relevant views.