Software Architectures (CS-701) Unit 5 Notes

How unit 5 is examined

This unit covers how an architecture is written down so others can use it. Marks sit in the principles of sound documentation, the seven-part documentation package and context diagrams; variability and interfaces are asked occasionally.

Principles of sound documentation

<span style="display:inline-block;padding:.16em .6em;border:1.5px solid currentColor;border-radius:999px;font-size:.68em;font-weight:700;letter-spacing:.06em;text-transform:uppercase;opacity:.75">High weight</span>

Definition. <mark>Sound documentation is architecture documentation that is written from the reader's point of view, is unambiguous, uses standard notation and is kept current, so that stakeholders can communicate, build, analyse and maintain the system from it.</mark>

Need. Documentation is the main means of communication between architect, developers, testers, managers and maintainers, it is the basis for analysing quality attributes, and it preserves design decisions for maintenance.

Key points.

Write from the reader's point of view: know who will read it (developer, tester, manager, maintainer) and what they need to find, and use their vocabulary.
Avoid unnecessary repetition: state each fact in exactly one place and refer to it elsewhere, so that the copies never disagree.
Avoid ambiguity: every box, line and symbol must have one meaning, and a legend or key must explain the notation so that no reader has to guess.
Use a standard organisation: a fixed template lets readers find information quickly and lets the writer see what is missing.
Record rationale: explain why a decision was taken and which alternatives were rejected, so later maintainers do not undo it blindly.
Keep documentation current but no more detailed than needed: outdated documents mislead, so update them with the architecture and stop at the detail stakeholders actually use.
Review it for fitness of purpose: let the intended readers check it and confirm it answers their questions.
Use standard notation such as UML where possible, and describe any informal notation used.

Impact. Sound documentation improves communication among stakeholders and cuts the cost of maintenance and analysis.

Answer frame. Open with the definition and the need (communication, analysis, maintenance); list stakeholders and their uses in one line; develop points 1-8 in this order with one sentence each; close by saying the architecture is only as useful as its documentation is readable and current. For Dec 2024, first define refinement (see next topic) in two lines.

Pitfall: Listing principles as bare words; add one explaining sentence each.

Asked: [7 marks] (Nov 2023, Dec 2025) What are the basic principles of sound documentation? Explain in detail. Asked: [7 marks] (Nov 2022) What is the need of documentation in software architecture? Describe the basic principles to follow. Asked: [7 marks] (Dec 2024) Define refinement. Explain the principles of sound documentation.

Refinement

Definition. <mark>Refinement is the process of taking a coarse architectural description and adding detail step by step, decomposing an element into finer elements until the level needed is reached.</mark>

Key points.

A high-level view is refined by replacing an element with its own internal structure, which is documented as a separate view.
Each refined view must stay consistent with the parent: the interfaces and responsibilities of the element are preserved.
Refinement lets each reader stop at the level of detail they need, and it is also called decomposition.

Context diagrams

Definition. <mark>A context diagram is a top-level view that shows the system as a single box and its relationships with the external entities (users, other systems, devices) that it exchanges data with.</mark>

Diagram. <figure class="ds-fig" style="margin:1.4rem 0;overflow-x:auto"><svg xmlns="http://www.w3.org/2000/svg" id="dsfig-u5-01" viewBox="0 0 510 295" width="510" height="295" role="img" aria-label="Context diagram. U = user, Sys = the system, DB = external database, Ext = external system"><style>#dsfig-u5-01 .e{stroke:#454C5A;stroke-width:1.4;fill:none}#dsfig-u5-01 .e.hi{stroke:#2340B8;stroke-width:2.6}#dsfig-u5-01 .n{fill:#FFFFFF;stroke:#16181D;stroke-width:1.4}#dsfig-u5-01 .n.hi{fill:#E3E9FC;stroke:#2340B8;stroke-width:2.2}#dsfig-u5-01 .n.rb-b{fill:#16181D;stroke:#16181D}#dsfig-u5-01 .n.rb-r{fill:#BD3227;stroke:#BD3227}#dsfig-u5-01 text{font-family:"JetBrains Mono",ui-monospace,Menlo,Consolas,monospace;font-size:13px}#dsfig-u5-01 .t{fill:#16181D;font-weight:500}#dsfig-u5-01 .t.inv{fill:#FFFFFF;font-weight:700}#dsfig-u5-01 .kd{stroke:#16181D;stroke-width:1.2}#dsfig-u5-01 .dot{fill:#16181D}#dsfig-u5-01 .ann{fill:#2340B8;font-size:11px;font-weight:700}#dsfig-u5-01 .lbl{fill:#6F7787;font-family:system-ui,-apple-system,sans-serif;font-size:12px;font-weight:700}#dsfig-u5-01 .ptr{fill:#2340B8;font-size:12px;font-weight:700}#dsfig-u5-01 .ah{fill:#454C5A}#dsfig-u5-01 .ah.hi{fill:#2340B8}#dsfig-u5-01 .wl rect{fill:#FFFFFF;stroke:#DCE0E7}#dsfig-u5-01 .wl .t{font-size:12px;font-weight:700}#dsfig-u5-01 .wl.hi rect{fill:#2340B8;stroke:#2340B8}#dsfig-u5-01 .wl.hi .t{fill:#FFFFFF}html.dark #dsfig-u5-01 .e{stroke:#B1B7C3}html.dark #dsfig-u5-01 .e.hi{stroke:#8FA3FF}html.dark #dsfig-u5-01 .n{fill:#161920;stroke:#E6E8ED}html.dark #dsfig-u5-01 .n.hi{fill:#1E2748;stroke:#8FA3FF}html.dark #dsfig-u5-01 .n.rb-b{fill:#E6E8ED;stroke:#E6E8ED}html.dark #dsfig-u5-01 .n.rb-r{fill:#FF7E71;stroke:#FF7E71}html.dark #dsfig-u5-01 .t{fill:#E6E8ED}html.dark #dsfig-u5-01 .t.inv{fill:#0F1115}html.dark #dsfig-u5-01 .kd{stroke:#E6E8ED}html.dark #dsfig-u5-01 .dot{fill:#E6E8ED}html.dark #dsfig-u5-01 .ann{fill:#8FA3FF}html.dark #dsfig-u5-01 .lbl{fill:#858D9C}html.dark #dsfig-u5-01 .ptr{fill:#8FA3FF}html.dark #dsfig-u5-01 .ah{fill:#B1B7C3}html.dark #dsfig-u5-01 .ah.hi{fill:#8FA3FF}html.dark #dsfig-u5-01 .wl rect{fill:#161920;stroke:#2A2E37}html.dark #dsfig-u5-01 .wl.hi rect{fill:#8FA3FF;stroke:#8FA3FF}html.dark #dsfig-u5-01 .wl.hi .t{fill:#0F1115}</style><defs><marker id="ah15" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path class="ah" d="M0,1 L9,5 L0,9 z"/></marker><marker id="ahh15" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path class="ah hi" d="M0,1 L9,5 L0,9 z"/></marker></defs><path class="e" d="M56.8,48.8 Q141.2,92.9 234.1,84.8" marker-end="url(#ah15)"/><path class="e" d="M238.2,74.2 Q153.8,30.1 60.9,38.2" marker-end="url(#ah15)"/><path class="e" d="M275.6,78.9 L449.4,44.1" marker-end="url(#ah15)" marker-start="url(#ah15)"/><path class="e" d="M255,236 L255,104" marker-end="url(#ah15)"/><g class="wl"><rect x="112.6" y="70.8" width="61.5" height="18" rx="9"/><text class="t" x="143.3" y="79.8" dy=".35em" text-anchor="middle">request</text></g><g class="wl"><rect x="128.1" y="34.2" width="47.1" height="18" rx="9"/><text class="t" x="151.7" y="43.2" dy=".35em" text-anchor="middle">reply</text></g><g class="wl"><rect x="342.1" y="52.5" width="40.8" height="18" rx="9"/><text class="t" x="362.5" y="61.5" dy=".35em" text-anchor="middle">data</text></g><g class="wl"><rect x="234.6" y="160" width="40.8" height="18" rx="9"/><text class="t" x="255" y="169" dy=".35em" text-anchor="middle">feed</text></g><circle class="n" cx="40" cy="40" r="18"/><text class="t" x="40" y="40" dy=".35em" text-anchor="middle">U</text><circle class="n" cx="255" cy="83" r="18"/><text class="t" x="255" y="83" dy=".35em" text-anchor="middle">Sys</text><circle class="n" cx="470" cy="40" r="18"/><text class="t" x="470" y="40" dy=".35em" text-anchor="middle">DB</text><circle class="n" cx="255" cy="255" r="18"/><text class="t" x="255" y="255" dy=".35em" text-anchor="middle">Ext</text></svg><figcaption style="font-size:.82em;opacity:.72;margin-top:.45rem">Context diagram. U = user, Sys = the system, DB = external database, Ext = external system</figcaption></figure>

Key points.

The elements are the system (one box), the external entities, and the labelled flows of data or control between them.
It defines the scope: whatever is inside the box is built, and whatever is outside is the environment.
It documents behaviour at the boundary only: what enters the system and what leaves it, not how it works inside.
It helps refinement, because the single box is later decomposed into the primary presentations and element catalogue, and each boundary flow must reappear as an interface of the refined elements, which keeps the documentation complete and consistent.
It is easy for non-technical stakeholders to read, so it fixes scope in discussion with customers and managers.
Example: an ATM system as one box, with the customer, the bank server and the cash dispenser as external entities and flows such as card, PIN and cash.

Answer frame. Open with the definition; draw the diagram with the system in the centre; explain elements, then scope, boundary behaviour and refinement; close with the example.

Asked: [7 marks] (Nov 2022, Jun 2025) What are context diagrams? How are they used to document software behavior? Demonstrate how context diagrams help in refining architecture documentation.

Variability

Definition. <mark>Variability documentation records the places where an architecture or its elements can differ between products or deployments, and the choices allowed at each.</mark>

Key points.

A variation point is a place where a choice is made, such as an optional element or a replaceable component, and the documentation states the options and the binding time.
Mechanisms include parameters, inheritance, plug-ins, configuration files and conditional compilation.
In a product line the common core is reused and only the variation points differ, so documenting them makes reuse and derivation of new products cheaper. Example: a phone family where the camera module is optional and the display driver is selectable.
It is recorded in the variability part of the template, with the rationale for each option.

Asked: [7 marks] (Jun 2025) Analyze the role of variability in architecture documentation with an example.

Software interfaces

Definition. <mark>An interface is the boundary across which elements interact; interface documentation states its name, operations with signatures, and the pre-conditions and post-conditions of each.</mark>

Key points.

Document each operation's name, parameters, return type and exceptions, which is its signature.
State pre-conditions (what the caller must guarantee) and post-conditions (what the element guarantees), together with the resources and quality attributes it affects.
Describe element behaviour with sequence diagrams, statecharts and protocol descriptions, showing the order of interactions.
Notations are UML for structure and behaviour, and an interface definition language such as IDL for the signatures.

Asked: [7 marks] (Dec 2025) How do you document software interfaces and the behaviour of software elements?

Documenting the behavior of software elements and software systems

Definition. <mark>Behaviour documentation describes how elements react over time to stimuli, complementing structural views that show only what elements exist.</mark>

Key points.

Sequence diagrams show the order of messages among elements for one scenario.
Statecharts show the states of an element and the events that cause transitions.
It is placed in the element catalogue for elements and in the behaviour section of a view for the whole system.

Documentation package using a seven-part template

Definition. <mark>A documentation package is the complete set of documents describing an architecture: the views, plus the information that applies beyond the views and across them.</mark>

Contents. Views, documentation beyond views, and cross-view information.

Key points. A view is documented with the seven-part template:

Primary presentation shows the elements and relations, usually as a diagram.
Element catalogue lists each element with its properties, interfaces and behaviour.
Context diagram shows the scope of the view and the environment.
Variability guide lists the variation points and how to exercise them.
Architecture background gives the rationale, and the analysis and constraints behind the design.
Glossary of terms and acronyms defines the vocabulary used.
Other information, such as open issues and references, is added as needed.

The package also holds the how-documentation-is-organised guide and the mapping between views. It is built by choosing views for stakeholders, documenting each with the template, and adding the cross-view material.

Answer frame. Open with the definition; list the seven parts with one line each; add the process (choose views, fill template, review); close with why stakeholders can find what they need.

Asked: [7 marks] (Nov 2023, Dec 2024, Jun 2025) What is the documentation package? Describe the seven-part template for it.

Last-minute revision

Sound documentation: reader view, no ambiguity, no repetition, standard notation, rationale, current, reviewed.
Refinement adds detail by decomposing elements, keeping parent interfaces.
A context diagram shows one system box, external entities and flows.
Variability lists variation points, options and binding times.
An interface gives signatures, pre-conditions and post-conditions.
Behaviour uses sequence diagrams, statecharts and protocols.
Package = views + beyond views + cross-view information.
Seven parts: primary presentation, element catalogue, context, variability, background, glossary, other information.

Memory hooks

Reader first, repeat never.
Refine means zoom in.
Context = one box, many neighbours.
P-E-C-V-B-G-O: primary, element, context, variability, background, glossary, other.

Coverage checklist

principles of sound documentation: Nov 2022, Nov 2023, Dec 2024, Dec 2025
refinement: Dec 2024 definition
context diagrams: Nov 2022, Jun 2025
variability: Jun 2025
software interfaces: Dec 2025
Documenting the behavior of software elements and software systems: Dec 2025 (behaviour part)
documentation package using a seven-part template: Nov 2023, Dec 2024, Jun 2025

Account

Software Architectures (CS-701) - Unit 5 Short Notes

How unit 5 is examined

Principles of sound documentation

Refinement

Context diagrams

Variability

Software interfaces

Documenting the behavior of software elements and software systems

Documentation package using a seven-part template

Last-minute revision

Memory hooks

Coverage checklist