Documenti di Didattica
Documenti di Professioni
Documenti di Cultura
2 IEEE 1471
Mission
Environment
Concern
System
Architecture
Stakeholder
Architecture
Description
Viewpoint
View
Library
Viewpoint
Rationale
Model
IEEE 1471 proposes that an AD consist of views and that views are constructed
according to viewpoints.
In the IEEE 1471 conceptual model a stakeholder is represented by his concerns.
Wherever in this document we mention stakeholder orientation we mean
orientation on the concerns of that stakeholder.
IEEE 1471 defines a view as A representation of a whole system from the perspective
of a related set of concerns (id, p.9), and a viewpoint as A specication of the
conventions for constructing and using a view. A pattern or template from which to
develop individual views by establishing the purposes and audience for a view and the
techniques for its creation and analysis. (id. p. 10).
This research focuses on the definition of viewpoints as the leverage point to improve
the quality of the architecture description, and more particular on improving the
insight in the relation of the architecture design to the concerns of the stakeholders,
before deciding on the viewpoints to use.
Viewpoints delineate the architectural information that is presented to the
stakeholder. @@@???For us this means paying explicit attention to the selection of
architectural information from the conceptual model of the architecture that will be
part of the view.
Viewpoints contains prescriptions for models to be use in the views. From our interest
in communication we intend to give additional guidelines on the use of text and the use
of diagrams in these viewpoints.
3 Hypothesis
The model described in this document is based upon the following hypothesis:
an IT-architecture lays the foundation for a development project for (parts of) one
of more IT-systems. I creates the frames for others to work in.
Though the situational approach is practice, it is not per se desirable. Where there
repeatedly can be made use of the same viewpoints, IEEE 1471 offers the possibility
of storing and reusing viewpoints as library viewpoints. This method can be used to
construct those library viewpoints or evaluate existing library viewpoints for
possible use in a given situation.
The smaller the number of views a stakeholder must consult to see how his
concerns are addressed, the better it is. The smaller the amount of unnecessary
information a view contains for a stakeholder, the better it is. Information that is
only for internal use by the architecture team should not be communicated to the
stakeholders.
Views contain the information that is needed to address a set of closely related
concerns of the stakeholders. Views form the top level structuring of the
architecture description. The division in views must be clear, which means that a
stakeholder must be able to easily determine which views are relevant to him/her.
Views are constructed after prescriptions thereof in corresponding viewpoints.
A viewpoint must prescribe a clear structure for the entailing view, which means
that a stakeholder can easily determine what kind of information the various parts
of the view contain and how this information relates to the concerns to be
addressed.
A clear structure also means a composition of layers of abstraction. For each layer
the information is complete, which means that the stakeholders can, remaining on
the same abstraction level, infer fully the meaning of this information. It is the
responsibility of the writer of the architecture description to construe these layers
of abstraction and to not leave the reader up to doing this himself. The architect
must be to himself clear about the priorities in the architectural decisions taken,
which are essential, which are of less importance. The hierarchy of meaning must
be clear.
The use of diagrams must be tuned to the frame of reference of the stakeholders.
The stakeholder must be able to easily perceive his place in the world of the
diagrams. The use of symbolic forms and of icons and colors must correspond to
what he is used or be easily recognizable by him. All the mean architectural
statements must be depicted graphically in the diagrams. The way the contents of
the diagrams mutually relates must be clearly discernable (for instance by similarity
in place and form of corresponding items). The diagrams must be consistent in the
use of visual attributes. The architectural concepts must be clearly recognizable in
the diagrams. See the guidelines for readability @@@[Koning 2001].
To clarify the content of a document to the reader, a concept map relating the
architectural concepts to each other will be experimentally provided in the
documents.
The use of text must be tuned to the frame of reference of the stakeholders. In
headings and body text the concerns should be recognizable. The language of the
body text should make use of terminology of the stakeholder, or terminology that is
familiar to the stakeholder.
There are three categories of concepts to discern: the concepts with which the
stakeholder daily operates, the concepts on which the architecture is based, and
the shared concepts of the environment in which the stakeholder and the ITarchitect work. These categories can be further differentiated into more levels of
familiarity and/or commonality. An accessible document leads from the known to
the unknown. If necessary the IT-architect must add translations of the ITarchitecture concepts to the concepts and concerns of the stakeholders.
Understanding an IT-architecture is basically a process of translating the ITarchitecture concepts to the own concepts of the stakeholder, and making
inferences about possible situations or results that may occur by introducing the ITarchitecture.
4 Model
This is the tentative model that shall be tested and corrected by means of the research
activities. The model is described in the following paragraphs.
The model contains the result of the collaborative learning that is part of the action
research activities. For a starting point the model has a hypothetical nature, it
expresses the common understanding, that will be tested by the research activities.
IT-architect
Stakeholder
Detailed design of
diagrams
Produce
architecture
descriptoin
Overall design of
viewpoints
Read
Detailed design of
textual description
The model consists of three design activities that proceed the actual production of the
architecture description. The fourth activity is the use of the architecture description
by the stakeholder. In the following sections each of these activities is described.
Documenting the architecture is an activity that takes place in all stages an
architecture design project. For internal discussion of for intermediate discussion with
stakeholders parts of the design under consideration are described, altered, and
described again. These pieces of description may have a varying degree of formality. In
the final stages of the project a roundup takes places of all available pieces of
description and an effort is made to check for completeness and to see to it that
documentation standards are met.
An extra effort may be made to produce clear documentation to serve the larger
audience that will be reached at the end of the project. This model presumes that a
conscious and substantial effort is made to produce stakeholder oriented
documentation that is very readable. It is up to the architect to decide when and where
he will perform these activities as long as in the end the proposed deliverables are
there.
Summarize
internal design
documentation
Compile
stakeholder
profiles
Relate summary
of internal design
documentation to
concerns of
stakeholders
Define viewpoints
This is a very essential activity. Basically it consists of tinkering around for a prolonged
period of time with the relation between the messages in the architecture design and
the concerns of the stakeholders. Various tools are provided for the stakeholder to
express and amend his thoughts, find omissions, seek words to express the perceived
relation, etc.
Since experienced architects probably are trained and molded in some general
applicable it-oriented documentation standard, it is important to take enough time for
this activity and allow yourself to grow into specific stakeholder perspectives.
There is some logical relation between the sub-activities, as shown in the figure from
left to right, but as with any design process, each part influences the others and while
progressing it may be necessary to come back and review previous results.
Probably this activity could (should?) be done in cooperation with stakeholders. That is
not worked out here, but is certainly not excluded and in fact probably a very valuable
thing to do.
4.2.1 Activities
be any type of information that has played a role in the design process somehow.
Examples are: concerns, design principles, goals, components, products, deadlines,
money, etc. Each concept can have subtypes depending on specific characteristics of
the architecture design.
Deliverables:
Stakeholder Profile Tables (see 5.2), one or two for each stakeholder
The text and graphics produced in this activity are not the final documentation, but
they will be of help in producing the final documentation and make that more smooth.
The effort put in producing this intermediate material will have a return on
investment later on.
Deliverables:
4.2.1.4Define viewpoints
Now this is what it is all about.
The viewpoints indicate what information will be presented to which stakeholders and
which concerns are addressed by this information. It also contains directions for
modeling techniques to be used and for how to assemble or verify the information.
This activity takes from the previous activities a well-founded insight into the relation
of the architectural design to the concerns of the stakeholders. A goal of designing
viewpoints is to present to each stakeholder exactly the information he needs regarding
his concerns. When he is presented more information, It should be easy for a
stakeholder to find the 25% - 50% of the total information in which he (on average) is
interested. This information should not be scattered.
Defining the viewpoints is a design activity in itself. It is a balancing act between the
interests of the stakeholders and the interests (and limitations) of the architect. On the
stakeholder side the goal is to give each stakeholder exactly the information he needs
in a way that suits him/her well. On the architects side there is the limited time
available and the practicalities of the distribution of the final documentation.
One of the viewpoints may concern mr. everybody as stakeholder and give a general
overview and any information not related to specific concerns that is common to all
stakeholders.
It seems only natural to capture the reasons for the choices made in this activity as
part of the rationale.
Deliverables:
Communication by means of diagrams has proven to be very effective in ITarchitecture and in IT-designing in general. By making it a separate activity the
architect is encouraged to reserve due time and energy for it and take is very
seriously. The image of the project is often carried by the diagrams, of the one
main diagram.
The use of colors, graphics and other visual aspects in diagramming offers very
good opportunities to connect to the situation of the stakeholder, and make the
information his information.
The use of visual attributes should be designed for all documentation at the start.
The visual representation of the main architectural concepts and messages should
be chosen with care and used consistently.
Use colors, graphics from the stakeholder environment, and that are meaningful to
him.
Produce extra diagrams with only the relevant information for the stakeholder.
Produce extra diagrams that equal general diagrams, but with added icons to show
stakeholder aspects.
Take a look at diagrams the stakeholder is used to, and where possible, follow
suite.
There is one specific thing the practitioners are asked to do and that is to offer the
stakeholders a concept map of the architecture description somewhere in the
introductory parts of the documentation.
Deliverables:
@@@
Making sure that relevant information is delineated by structure elements (dont let
the stakeholder search for relevant information in unstructured text).
(combi with diagrams) design a set of icons related to the main architectural
messages and recognizable / meaningful to the stakeholders; add these icons to
the text or the page border
Deliverables:
@@@
5 Deliverables
5.1 Summary of internal design documentation
The summary of internal design documentation is a simple list of all the main
architectural statements. It is a listing, it is not the full description of the architectural
statements.
For an existing (classical) architecture description a detailed outline of content can be
used.
Meaning
Title
Goals
Tasks
Concepts
Concerns
Example:
Attribute
Content
Title
Goals
Tasks
Concepts
Concerns
This is a small example of a concept map of a new data-architecture that was designed
for a company. The concepts are in black, the main architectural statements are in
gray.
FD and
applications
maintained in
coordination
Functional
design
Application
All applications
which access
data are known
Functional datacomponent
Design principles
guide the
mapping of
functional
component to
data access
functions
Data Access
Function
There is a limited
number of
sufficiently
functional data
access functons
Data Entity
Relation
The technical
structure is better
maintainable in
coordination with
the data access
functions
Summary of
GTP
Architecture
Report
Acquirer
Process designer
Domain Architect
How to
prepare the
organisatio
n for the
new
solution?
.
.
.
How can I
Can I design a clear
administer the new process wit hit?
regulations
efficiently?
Information
Manager
.
.
.
Which regulations
Which regulations
can be administered have clear process
more efficiently?
steps?
3.2
Considered
regulations
A more efficient
A selection has been
administration is
done on the basis of
realisable when
the number of
regulations have a process steps and
strong resemblance the clearness and
and need no extra needed authority of
contacts with clients. decisions.
3.3.1 Scope
in business
process
model
Which departments
and/or workprocesses
are touched by the
changes and how?
The impact is indicated
in an organisation
description dd ....; a
distinction is made
between small changes
(process continues)
and big changes
(temporary measures
will be needed)
@@@try concerns in the map, close to one or more concepts they are related to,
instead of on the side, and dont connect to stakeholder (use colors to indicate
stakeholders, or make a diagram for each stakeholder)@@@
As an example:
A viewpoint name
The stakeholders to be addressed by the viewpoint
The concerns to be addressed by the viewpoint
The language, modeling techniques, or analytical methods to be used in
constructing a view based upon the viewpoint
e) The source, for a library viewpoint (the source could include author, date, or
reference to other documents, as determined by the using organization)
See IEEE 1471 sections 5.3 and 5.4 (on views) for the complete prescription for
viewpoints.
Different modeling techniques can be combined in one view to represent all the
information needed to address the concerns. See [Clements, 2003] for a thorough
description of proven modeling techniques. Paragraph 5.7.1 offers a short introduction
to this book.
Some additional guidelines:
Style
Decomposition
Uses
Generalization
Layers
Component-andConnector
Allocation
Pipe-and-Filter
Shared-Data
Publish-Subscribe
Client-Server
Peer-to-Peer
CommunicatingProcesses
Deployment
Implementation
Work-Assignment
5.8 Rationale
IEEE 1471 (section 5.6) prescribes for the Rationale:
An AD shall include the rationale for the architectural concepts selected. An AD should
provide evidence of the consideration of alternative architectural concepts and the
rationale for the choices made. When the AD describes a system that pre-exists the
development of the AD, the rationale for the legacy system architecture shall be
presented, if known.
6 References
[Clements, 2003] Clements et. al., Documenting Software Architectures: Views and
Beyond, 2003, Addison-Wesley, ISBN 0-201-70372-6
[Gyselinck 1999].@@@
[Koning, 2001] @@@ guidelines readability @@@