Document Architecture

Document Architecture SL Training Group 2006

Edsger Dijkstra, The inventor of many of the software engineering principles we take for granted, once said that “he will happily spend two hours pondering how to make a single sentence clearer” Reasons Dijkstra’s caliber Can save each reader a minute or two of confusion Software Documentation Principle

Documentation should be written from the point of view of the reader, not the writer. Avoid repetition. Avoid unintentional ambiguity. Use a standard organization. Record rational Keep it current Review documentation for fitness of purpose. 7 Rules for Software Documentation

Document written for writer take two form which need to avoid Stream of consciousness Stream of execution Corollaries Document should be organized for ease of reference, not ease of reading. Mark what you don’t yet know with “to be determined” rather than leaving it blank. Rule 1: Write for the reader

Each kind of information should be recorded in exactly one place. Easier to use Easier to change It avoid confusions Nothing wrong with providing multiple access routes or entry points to a section that contain specific kind of information. Expressing the same idea in different forms is often useful for achieving a thorough understanding Rule 2: Avoid Repetition

Planned ambiguity Architecture should not ambiguous, but planned ambiguity is necessary. Avoid linguistic ambiguity A well-defined notation with precise semantics Box-and-line diagrams are ambiguous. Rule 3: Avoid unintentional ambiguity

Document should be conformed to Standard Planned Organization scheme which should be made known to the reader. IEEE Recommended Practice for Architectural Description: provides vocabulary for talking about architectural issues. provides framework for documenting, promulgate and improve architectural existing and new practices. Rule 4: Use a standard organization

If you are documenting the results of decisions Record the decisions you eschewed and say why Recording rationale will save you enormous time in the long run. Although it is time consuming, requires discipline to record. Rule 5: Record rationale

Following documents are does not reflect truth and does not obey its own rules for form and internal consistency Incomplete documents Out-of-date documents Use document that is kept current and accurate Fix documentation if inadequate to answer the questions. Final authoritative source Updating it and Then referring the questioner Rule 6: Keep it current

Only the intended users of a document will be able to tell you if it contains the right information presented in right way. Validate before release Rule 7: Review documentation for fitness of purpose

Documenting an architecture is primarily a matter of documenting the relevant views of that architecture, plus recording information that applies to more than one view. Axiom Testers & Integraters Re-engineers QA Managers Designers & Implementers Component Engineers

Architecture is a forum for negotiating and making trade-offs among competing requirements. Architect & Requirements engineers

Architecture is a vehicle for arbitrating resource contention and establishing performance and other kinds of run-time resource consumption budgets. Architect and Component designers

The architecture establishes the possibilities for commercial off-the-shelf (COTS) component integration by setting system and component boundaries and establishing requirements for the required behavior and quality properties of those components. COTS Evaluators

The architecture serves as the fodder for architectural evaluation methods such as the Software Architecture Analysis Method and the Architecture Tradeoff Analysis Method (ATAMSM) and Software Performance Engineering (SPE) as well as less ambitious (and less effective) activities such as unfocused design walkthroughs. QA Analyst

Architecture provides the formal model that drives analytical tools such as rate monotonic schedulers, simulations and simulation generators, theorem provers and model checking verifiers. QA Engineer (Performance Engineer)

The architecture determines whether a potential new member of a product family is in or out of scope, and if out, by how much. Manager (Product line)

Architecture is basis for conformance checking, for assurance that implementations have in fact been faithful to the architectural prescriptions. Technical Manager

Architecture is a starting point for maintenance activities, revealing the areas a prospective change will affect. Maintainers

The architecture is usually the first artifact for familiarization with a system’s design. New Member

The architecture is the artifact that (if properly documented) preserves that architect’s knowledge and rationale. Architects

Architecture is the often first artifact recovered from a program understanding activity or (in the event that the architecture is known or has already been recovered) the artifact that drives program understanding activities at component granularities. Re-engineers

An architectural overview An architectural reference manual Kind of Architecture Documentations

providing a shared understanding of the architecture across a broad produced early in the development lifecycle and serves as the starting point for the development. high level of abstraction. All the major functionalities and components of the architecture should be described but the descriptions may lack detail precision as they often use natural language rather than formal notations Architectural Overview

Describes an architecture in a detailed and precise manner. A living document that is constructed collaboratively by the development team as the development proceeds. Used to track progress of the software development and for assessing the impact of proposed requirements changes. Complete reference manual is the basis for system maintenance and enhancements. Manual should be updated as changes occur so it always reflects the actual architecture Complete in the sense that every facet of the architecture should be documented. Use separate manuals for very large grained components For any particular aspect, technical or business risk associated with The level of completeness, formality, detail and precision Architectural reference manual

The template has been structured according to the 4 views of the 4+1 view model The logical viewis modeled in the structure section and the dynamic behavior section, Other view sections The process view, The implementation viewand the deployment view Template based on 4+1 architecture

… Template based on 4+1 architecture

The introduction section identifies the architecture and its stakeholders, And it records the creation and subsequent modification to the architecture documentation. Details to be captured include: name of the architecture architecture design team and author of the architecture document with information on who to contact to provide feedback for the architecture and its documentation creation and modification history audience and purpose selected viewpoints related documents Section: (i) Introduction

Should state whether the document is an architectural overview or a reference manual, Who the stakeholders and the intended readers are, And what the intended purposes of the document are. It should also record the relationship to any other documents associated with the development of the software, e.g. System Requirements Specification, System Architecture Specification, Design Specification, Internal Reference Specification, etc. Optionally, the selected viewpoints can be listed together with the stakeholders, and the issues addressed by each viewpoint, and a list of the sections of the architecture document containing descriptions and models for the selected viewpoints. When there is a single product associated with the architecture this section may optionally contain information regarding the project/product using the architecture like project name, release date, project team, or product team. … Section: (i) Introduction

Section (ii) System Purpose (a) (b) (c)

This section briefly and informally describes the context of the system and the problem that it solves. The aim is to provide an introduction to the system that is accessible to non-domain experts. The problem description should enumerate the key entities involved with the system and how the system provides value to them. The focus of this section is on the entities interested in and communicating with the system, and On the roles of these entities, not on the system itself. Section (ii.a) Context

The context diagram can be one of the following: an object or class diagram showing the system under consideration, other systems interacting with this system or otherwise valuable for understanding the context, and all important associations, a high-level use case diagram showing the system, its actors, and the most important use cases, a data flow diagram showing the data and control flows between the system and other entities in its environment Section (ii.a) Context : Context Diagram CellKeeper ,Exercise 1?

Documents the services that the system provides in terms of responsibilities. Often the system interface may be organized into a set of sub-interfaces, Each sub-interface corresponding to a distinct usage of the system, e.g. there may be specific interfaces for system configuration, for normal system use, and for system management. Interfaces may be defined at varying levels of detail and precision. In an architectural overview document the system interfaces will be described at a very high level of abstraction with optionally simply listing. In an architectural reference manual all the use cases or system operations of an interface will be listed and given a short description. Section (ii.b) System Interface CellKeeper ,Exercise 2?

summary of those requirements that address aspects of the system besides functionality and that are relevant for the system architecture. Non-functional requirements can be divided into three types: Qualities Constraints Principles Section (ii.c) Non-functional requirements CellKeeper ,Exercise 3?

Describe the static structure of the architecture in terms of its logical components and their interconnections. Logical components are units of responsibility on a specific abstraction level. A component may correspond to a single class or a group of implementation classes. Components on a high abstraction level are often called subsystems. Section (iii) Structure Note: Unless mentioned otherwise, in this section the term component is used to denote a logical component.

Section (iii) Structure (b) (c) (a)

Describes the topology of the architecture. An architecture diagram for the logical view is conveniently expressed using the UML class diagram notation. The structural overview comprises one or more architecture diagrams: system is represented as a composite aggregation of all its components. Optionally, interfaces can also be shown by using the round interface symbol. Commentary: rationaleof the architecture, outlines architecture styles and patterns, specifies any architectural constraints, and optionally also mentions alternative architecturesnot chosen Section (iii.a) Overview CellKeeper ,Exercise 4?

The rationale behind the architecture gives the reason why a particular topology and architecture style has been chosen and why particular components exist. It relates the architecture to higher level business objectives. It explains how the architecture satisfies the architecture requirements documented in architecture requirements documents and constraints Section (iii.a) Overview: commentary - rationale

Architectural constraints are important rules or principles governing component behavior or intercommunication, they are closely connected to the architectural styles chosen. If such a rule is violated then the architecture cannot be guaranteed to work correctly. Section (iii.a) Overview: commentary - constraints

If alternative architectures have been considered, the commentary should also mention or reference these architectural concepts and Give the reasons for not choosing them. Section (iii.a) Overview: commentary - alternatives

An architectural style defines a family of systems in terms of a pattern of structural organization. Thus it is a set of rules, which determines a set of components and the manner in which they should be connected together. Examples for architectural styles and patterns are: Layers Pipes and Filters Broker, service discovery Model-View-Controller Event based communication Section (iii.a) Overview: commentary - styles

System with mix of high-level and low-level abstractions and issues Where high level operations rely on lower level ones Components are grouped into layers (subsystems) where each layer only uses operations and has associations to components from the next lower layer. Variant: associations are allowed to components from any lower layer Layers

System whose task is to transform a stream of data. Each processing step is encapsulated in a filter, data is passed through pipes between adjacent filters. Pipes and Filters

For distributed systems, it is desirable to loosely couple the client from the service provider. A broker is used for registering, discovering and connecting to services. Optionally, the broker also takes care of forwarding and marshalling all communication between client and server. Broker, service discovery

System that needs to allow the user interface to change without affecting the underlying data. System functionality and data is separated into user interface (view and control) and model (business data and functionality). Model-View-Controller

Systems where certain components communicate with each other via implicit invocation instead of direct procedure calls. Components can subscribe to events published by other components. Variants: pushing or pulling events, event channels. Event based communication CellKeeper ,Exercise 5?

Section (iii.b) Components: • This section describes each component in the architecture. • A component is documented using the following template: • Componentis a unique identifier for the component. • Responsibilitiesprovided interfaces, and rationale. • Collaboratorsare other components that the component interacts with. • Notesis Information about multiplicity, concurrency, persistency, parameterization, etc. • Issuesare list of issues that remain to be resolved.

Each component should have a unique name and possibly a version number. This section can also contain references to the component design documentation and to the implementation. In case of a complex component that has been broken down into subcomponents, also add the reference to the chapters or to the architecture document describing the internal structure of the component. Component

Describes the purpose or job description of the component in terms of the component’s responsibilities, the interface(s) that it provides. A responsibility is a “piece of functionality” and specifies the purpose of the component. It can be information that the component has to know, or an action that it knows how to perform. Responsibilities

Interfaces can be listed by reference to named interface specifications in section (iii).c Interfaces, or by explicitly listing and describing the use cases or operations that constitute the interface in the same way as they are described in section (iii).c Interfaces. Referencing named interfaces facilitates component “plug and play”. Useful to document the rationale for the component Interfaces

Document Architecture