Documenting Software Architectures in Agile Development Environments

Software development teams in many organizations enforce architecture standards, but in most teams the reference architecture and design standards are not well documented or well managed over time. Having a software architecture documentation and architecture validation goes a long way. It promotes consistency in the System and helps the architects and developers to evaluate the architecture and use the architecture document go guide the implementation (design and code).

The main focus of this technical session is to present the concept of Documenting Software Architectures, especially in an Agile software development environments where design and architecture concerns often take a side-seat compared to coding. I will discuss an architecture documentation template that can be used in all IT projects to produce a consistent and easy to follow design document. I will also talk about the best practices and “gotchas” in documenting Software Architectures as well as the future trends in Software Architecture Documentation.

Software development teams in many organizations enforce architecture standards, but in most teams the reference architecture and design standards are not well documented or well managed over time. As a result of this lack of reference architecture documentation, the Implementation (Code) often doesn't match the Requirements (Reference Architecture) and the architecture quality suffers in the long run. Having a software architecture documentation and architecture validation goes a long way. It promotes consistency in the System and helps the architects and developers to evaluate the architecture and use the architecture document go guide the implementation (design and code).

The architecture of a system does not occur in a day. It has to be developed iteratively in the analysis, design, and development phases of an IT project. So, it is very important to document the software architecture in an organization. The main focus of this technical session is to present the concept of Documenting Software Architectures, especially in an Agile software development environments where design and architecture concerns often take a side-seat compared to coding.

Software Architecture can be described using Views (also known as Viewpoints or Perspectives) which are the representation of a set of system elements and the relations associated with them. Architecture Views are used to represent the system architecture using modeling specifications like UML 2.1, BPMN and other standards.

I will discuss what information, about an architecture, should be captured so that others can successfully use it, maintain it, and build a system from it. I will talk about the factors (business and technology) that influence the system architectures and how to align architecture efforts with business goals.

There are four different views that represent the system from different aspects. These are Design/Module, Build Time, Runtime, Deployment and Data Model Views. I will discuss the context of each view and its uses in the enterprise architecture big picture. I will also cover in detail, a framework we developed for documenting system architectures.

Other items included in the discussion are:

An architecture model that can be used in Agile Software Development process to capture the design and architecture details of an application.

Provide an architecture documentation template that can be used in all IT projects to produce a consistent and easy to follow design document. The Template document includes the architecture elements that add value to the software development process such as:

Document Road Map
Visual Models
Assumptions and Constraints
Architecture analysis and rationale
Mapping requirements to architecture for traceability purposes

I will also talk about the best practices and “gotchas” in documenting Software Architectures as well as the future trends in Software Architecture Documentation. Some of the architecture best practices include layered architecture, separation of concerns, domain-driven design.

Key Take-aways:
Overview of multiple views to represent software architecture
Role of UML 2.0 in documenting the software architecture View
How the architecture Views can we used to manage the quality attributes (performance, availability, modifiability, security)
Best practices and guidelines to make the architecture documentation valuable and more effective in software development environments especially those using Agile methodologies.

About Srini Penchikala

Srini Penchikala currently works as an Enterprise Architect at a major financial organization in Metropolitan Detroit area. He has over 14 years of IT experience and has been working on Java projects since 1996 and J2EE technology since 2000. His main areas of interest are Agile Enterprise and Service Oriented Architectures, Domain Driven Design & Development In Practice, Aspect-Oriented Programming (AOP), Architecture Rules Enforcement, Enterprise Integration Patterns, and light-weight middleware frameworks such as Spring and Hibernate. He has presented at conferences and Java User Groups on topics like Agile Enterprise Architectures, Architecture Governance, and Domain-Driven Design. He has published numerous articles on J2EE topics on websites like InfoQ.com, ServerSide.com, O'Reilly Java Network (ONJava), DevX Java, java.net and JavaWorld. Srini also publishes a blog on Java, JEE, and other topics at http://srinip2007.blogspot.com/. He is also a leader of Detroit Java User Group (http://sites.google.com/site/detroitjug/).

More About Srini »