Tips & Tricks to build software architecture document

Tips & Tricks for documenting Software
architecture
Karthikeyan VK
Karthik_3030@yahoo.com
@karthik3030
https://blogs.karthikeyanvk.in

Enter Text
Why Document Software Architecture?
Record important decisions.
One place to understand, how different system works with each
other.
Makes your platform scalable.
Common understanding among stakeholders

Enter Text
Good software architecture doc means?
Strong and easy to maintain even on add/change in features.
Domain concepts and boundary clearly specified.
Flexible, extensible, and usable for the long term.
Responds positively to change.

Enter Text
Mindset to Build architecture document
Everything changes.
Address only what customer wants
Address all stakeholders
Don’t over-architect
Decision tracker

Enter Text
Architecture documentation – Principles
Addressing Stakeholder concerns
Effective Communication (KISS)
Should be structured, Fluid in nature
Pragmatic, addresses real world & practical concerns
Flexible
Technology agnostic

Enter Text
Principles architecture document
Integrate with Software life cycle
Aligns with Engineering practises and quality management
standards.

Enter Text
Architecture Document
Viewpoints
Perspectives

Enter Text
What is Architectural Concern
A concern is a requirement, an objective, an intention for that
architecture.
Every viewpoint has its own concern
E.g.:- Development Viewpoint – Module organization Concern
E.g.:- Functional viewpoint - External interfaces

Enter Text
What is a Models
A model is a abstract representation of some aspects of
architecture.
Helps to understand.
Medium to communicate.
Eg:- Entity-relationship model, state transition model

Enter Text
Why Viewpoints
Architecture document is very complex because it tries to
capture everything in a single place
Such a model is hard to understand and is unlikely to clearly
identify the architecture’s most important features.
Viewpoint attack the problem from different directions
simultaneously.

Enter Text
What is a Viewpoint
Each viewpoint address the concerns .
It defines the stakeholders whose concerns are reflected in the
viewpoint and the guidelines, principles, and template models
for constructing its views.

Enter Text
Different types of Viewpoints
Functional
Information
Concurrency *
Development
Deployment
Operational

Enter Text
Why Viewpoints ?
A. Representing everything in a single model is complex,
viewpoints attacks using different models and views
B. Just another way of representing the architecture, nothing
different

Enter Text
Functional Viewpoints
Describes the relationships, dependencies, and interactions
between the system and its environment.
People, Systems, and External entities with which it interacts.

Enter Text
Functional Viewpoint - Concerns
Functional capabilities
External interfaces
Internal structure
Functional design qualities

Enter Text
Functional Viewpoint - Concerns
Functional design Philosphy
Separation of concerns
Cohesion/Coupling
Element Interaction
Flexibility
Overall Coherence

Enter Text
Functional Viewpoint - Models
Functional Structure models
Functional Elements
Interfaces
Connectors
External Entities.

Enter Text
Petshop

Enter Text
Models - Petshop

Enter Text
Functional Viewpoint - Pitfalls
 Poorly defined interfaces
 Poorly understood responsibilities
 Infrastructure modelled as functional elements
Overloaded view

Enter Text
Functional Viewpoint - Pitfalls
Diagrams without element definitions
Difficulty in reconciling the needs of multiple stakeholders
 Wrong Level of detail
 ‘God’ elements

Enter Text
Information Viewpoints
Describes the system’s functional elements, their responsibilities,
interfaces, and primary interactions
It drives the shape of other system structures such as the
information structure, concurrency structure, deployment
structure.
Basically everything you do with database or any storage.

Enter Text
Information Viewpoint - Concerns
Structure and content
Purpose and usage / Ownership
Mappings
Storage models/Flow/Consistency/Quality
Timeliness, latency, and age.

Enter Text
Information Viewpoint - Models
Static information structure models
Information flow models
Information lifecycle models

Enter Text
Metadata models
Data Format
Meaning
Data Structure
Data Context
Data Quality

Enter Text

Enter Text
Information Viewpoint - Pitfalls
Overloaded central database
Inconsistent distributed databases
Poor information quality
Representation incompatibilities

Enter Text
Development Viewpoints
Describes the architecture that supports the software
development process.
Development views communicate the aspects of the architecture
of interest to those stakeholders involved in building, testing,
maintaining, and enhancing the system.

Enter Text
Development Viewpoint - Concerns
Module organization
Common processing
Standardization of design/Design patterns
Standardization of testing
Instrumentation
Codeline organization

Enter Text
Development Viewpoint - Models
 Module structure
 Common design or Design patterns
 Codeline models or how code is organized in your Source control

Enter Text
Development Viewpoint - Models

Enter Text
Development Models – Petshop

Enter Text
Development Viewpoint - Pitfalls
Too much detail
Lack of developer focus
Lack of precision
Problems with the specified environment or maturity of the
technology

Enter Text Deployment Viewpoints

Enter Text
Deployment Viewpoints
Describes the environment into which the system will be
deployed, including capturing the dependencies the system has
on its runtime environment.
This view captures the hardware environment that your system
needs

Enter Text
Deployment Viewpoint - Concerns
Runtime platform required
Specification and quantity of hardware or hosting required
Third-party software requirements
 Technology compatibility
Network requirements/Capacity
Physical constraints

Enter Text
Deployment Viewpoint - Models
 Runtime platform models
Network models
Technology dependency models
Intermodal relationships

Enter Text
Deployment Viewpoint - Models

Enter Text
Deployment Models - Petshop

Enter Text
Deployment Viewpoint - Pitfalls
Unclear or inaccurate dependencies
Unproven technology
Unsuitable or missing service-level agreements
Lack of specialist technical knowledge

Enter Text
Deployment Viewpoint - Pitfalls
Late consideration of the deployment environment
Ignoring inter-site complexities
Inappropriate headroom provision
Not specifying a disaster recovery environment

Enter Text
Operational Viewpoints

Enter Text
Operational Viewpoints
Describes how the system will be operated, administered, and
supported when it is running in its production environment.
The aim of the Operational viewpoint is to identify system-wide
strategies for addressing the operational concerns

Enter Text
Operational Viewpoint - Concerns
Installation and upgrade
Functional migration
Data migration
Operational monitoring and control
Alerting

Enter Text
Operational Viewpoint - Concerns
Configuration management
Performance monitoring
Support
Backup and restore
Operation in third-party environments

Enter Text
Operational Viewpoint - Models
Installation models
Migration models
Configuration management models
Administration models
Support models

Enter Text
Operational Viewpoint - Models

Enter Text
Operational Viewpoint - Pitfalls
Lack of engagement with the operational staff
Lack of backout planning
Lack of migration planning
Insufficient migration window
Missing management tools
Production environment constraints or no sandbox

Enter Text
What are Perspectives
All the –ities
Security, quality, Availability, Scalability.
Resilience
Performance
Evolution

Enter Text
Perspectives - Performance
If your system requires high performance, you need to manage
the time-based behaviour of elements and the frequency and
volume of inter-element communication.

Enter Text
Perspectives – Evolution/Maintainability
If modifiability is important, you need to assign responsibilities to
elements such that changes to the system do not have far-
reaching consequences.

Enter Text
Perspectives - Security
If your system must be highly secure, you need to manage and
protect inter-element communication and which elements are
allowed to access which information.
You may also need to introduce specialized elements (such as a
trusted kernel or containers) into the architecture.

Enter Text
Perspectives - Scalability
If you believe scalability will be needed in your system, you have
to carefully localize the use of resources to facilitate the
introduction of higher-capacity replacements.

Enter Text
7 - Simple tips & Tricks to follow
Think in paper.
Build simple table structure document, whereever possible.
Use the whiteboard and take photo and save the model in
document
Explain the models to your developers/stakeholders and
brainstorm

Enter Text
Add explanation for every Diagram of every viewpoint
Your visual diagram should have a legend.
Add Brief details on path not taken in every viewpoint and
why it was not taken.
7 - Simple tips & Tricks to follow

Enter Text
References
@karthik3030
• http://www.ece.ubc.ca/~matei/EECE417/BASS/ch02lev1sec4.html

Enter Text
Networking and more
@karthik3030
• https://www.facebook.com/aspiringDotnetArchitects/
• https://www.meetup.com/Chennai-Microsoft-Azure-User-Group/
• https://www.youtube.com/channel/UCJxa58lDcDj4tYQIHh7ORxA

Enter Text
@karthik3030
Thank you
/Q&A

Tips & Tricks to build software architecture document

Recommended

Recommended

More Related Content

What's hot

What's hot (19)

Similar to Tips & Tricks to build software architecture document

Similar to Tips & Tricks to build software architecture document (20)

More from Karthikeyan VK

More from Karthikeyan VK (20)

Recently uploaded

Recently uploaded (20)

Tips & Tricks to build software architecture document