UNIT–5 (Simplified & Easy Notes)

Software Architecture Documentation

✅ What is Software Architecture Documentation?

It explains how the software system is structured.
Helps developers understand system components, modules, and design, without reading code.
Works as a communication tool between architect, developer & stakeholder.

⭐ Goals of Documentation (Very Important)

Knowledge Sharing
- Helps new developers understand the system quickly.
Communication
- Architects share design ideas with developers.
Analysis & Review
- Used to check if architecture meets requirements.

⭐ Two Ways to Create Architecture

1. Top-Down Approach

Start from big design → break into smaller parts.
Used when system requirements are clear.

2. Bottom-Up Approach

Start from small components → combine to form system.
Used when building systems step-by-step.

⭐ Principles of Sound Documentation (Super Important – Exam Repeated)

Principle 1: Write from reader’s point of view

Make document clear depending on user (developer/architect).

Principle 2: Avoid repetition

Use one definition or diagram and refer it everywhere.

Principle 3: Avoid ambiguity

Use clear language, UML diagrams, precise terms.

Principle 4: Use standard organization

Follow a fixed template/structure.

Principle 5: Record rationale

Write WHY a design decision was taken.

Principle 6: Keep documentation current (but not too current)

Update documentation but do not change it unnecessarily.

Principle 7: Review documentation

Check if documentation is useful and correct.

⭐ Refinement (Simple Explanation)

Refinement = adding more detail step-by-step.

Start with a high-level design
Add details in each step
Final stage = full code

Opposite of Abstraction

Abstraction hides details
Refinement adds details

⭐ Context Diagram (Very Important)

Meaning

Context diagram shows:

System as one single box
All external entities interacting with it
Data flowing in and out

Purpose

Defines system boundaries
Shows interactions with outside systems
Helps understand system scope

⭐ Variability (Simple Meaning)

Variability = ability of software to be changed or customized.

Used for:

Creating multiple versions of same software
Reusing components
Making flexible systems
Delaying certain design decisions

Example:
An app offering Basic, Pro, and Enterprise versions.

⭐ Software Interfaces (Easy Words)

Interface = a connection point where two software components talk to each other.

Examples:

API
Function calls
Message passing
Data streams
Shared memory

Key Points:

Every component has an interface
Interface tells what a component can do
Components talk through interfaces

⭐ Documenting Behavior of Software

We document how software behaves, especially dynamic behavior.

Techniques:

Sequence diagrams — object interaction
Activity diagrams — workflow
State machine diagrams — states & transitions
Use-case scenarios — user interactions

⭐ Types of Documentation

1. Product Documentation

Describes the product.

Includes:

Requirements
Design documents
Architecture docs
User manuals
Installation guides

2. Process Documentation

Describes the development process.

Includes:

Project plans
Test reports
Meeting notes
Schedules
Standards

Difference:

Product documentation → about the software
Process documentation → about how the software was built

⭐ Documentation Package (Seven-Part Template)

(VERY IMPORTANT – Direct exam question)

Each architecture view has 7 parts:

1. Primary Presentation

Main diagram showing components & relations.

2. Element Catalog

Descriptions of all elements (components, modules).

Includes:

Properties
Relations
Interfaces
Behavior

3. Context Diagram

Shows system’s interaction with environment.

4. Variability Guide

Explains how parts of architecture can change or be customized.

5. Architecture Background

Explains why architecture is designed this way.
Includes:

Rationale
Assumptions
Analysis results

6. Other Information

Change history, references, configuration info.

7. Related View Packets

Links to parent/child or related architecture views.