Architecture Document

Basics

  • After the code the document is the primary holder of system quality attributes.
  • It should be written in a way to be useful for all stakeholders in all levels. Not everyone reads SAD in the same way.
  • The first step in writing SAD is to know stakeholders and which views they are interested in.
  • SAD is used for communication, education, analysis, etc.
  • The most important part of a SAD is to document views and details that apply to more than one view (cross view).
  • Which views to pick for SAD depend on the quality attributes of most concern to the stakeholders/system.
  • Decomposition view or users view apply to almost every system but not all view apply to every system; for example client server view will apply only to systems designed that way.
  • The level of detail every stakeholder need from each view is also different ranging from none or overview to moderate and detail.

Documenting a View

Sections on documenting each view could be:

  • Initial presentation of the graphical/tabular or textual form
  • Catalogue of elements
  • Main context diagram
  • Background : How and why we came to this conclusion.
  • Glossary

It is important to highlight a particular analysis that is related to this view.

Documenting Behaviour

Views do not necessaries represent behaviour. To convey behaviour of an element (or a group of elements) use sequence diagrams and state diagrams. These two diagrams can answer availability and performance questions.

Documenting Interfaces

This is also an important part of the SAD. We have to write syntax, semantic, data type, usage guide, exceptions, design issues, etc

A sample template

  1. Project Context
  2. Architecture Requirements
    1. Overview of Key Objectives
    2. Architecture Use Cases
    3. Stakeholder Architectural Requirements
    4. Constraints
    5. Non-functional Requirements
    6. Risks
  3. Solution
    1. Relevant Architectural Patterns
    2. Architecture Overview
    3. Structural Views
    4. Behavioral Views
    5. Implementation Issues
  4. Architecture Analysis
    1. Scenario analysis
    2. Risks
Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License