Skip to content


Repository files navigation

Title Subtitle Author
Documenting and Understanding Software Systems
Neil Ernst

Schedule and Topics - Fall 2019

The following schedule is subject to change. All deadlines and due dates listed here are the official dates.

See also tentative schedule

This semester I'm doing the schedule differently. Instead of detailed day by day schedules, I'll list the main modules, the slides, and then key dates. Modules are sequential, and I aim to do one module per week. If you miss a class, I assume you can figure out what you missed. If not, see your classmates.

Lectures are T,W,Fr 10:30am-11:30am in ECS 124.


Topic Other Resources Readings
What is Software Architecture? text chapter 1
Software arch overview text chapter 2 ; Architect Roles Map; Gregor Hohpe's architect roles
Reading Code. chapter 3 text, source code of web crawlerFB's GetafixPetronella TweetHackerNews on Arch
Architecture Stakeholders and Requirements. text chapter 16
Views on Architecture - Modules, C&C , Allocation SEI view example text chapter 18
Documenting behavior SEI behavior tech report
Architecture analysis text chapter 21
Technical Debt and Metrics my Field Study of TDmetrics and TD
Interface Documentation
Reviewing Docs Guidelines for Doc Reviews
Microservice Styles
Serverless Styles
Distributed/Concurrent Styles
Functional Styles
Event-Driven Architectures

Key Dates

Event Deadline
Project: M0 September 13
Project: M1 September 25
Project: M2 Oct 4
Thanksgiving Day Oct 14
Project M3 Oct 25
Undergrad Assign/Grad topic Oct 25
Reading Break Nov 11-13 (no class)
Midterm Nov 8
Project M4 Nov 15
Doc Exercise in class Nov 22
Project M5 Nov 22
Project summaries in class week of Dec 2
Last class Dec 4
Project M6 and M7 due in repo Dec 9
Grad assignment due Dec 13


Software is a long-lived and complex thing. This course is about understanding software in the large. We use the SEI text as a framework for understanding large-scale software systems. Topics include

  • what is architecture? Who are architects?
  • what structures are important to understand?
  • views on software systems
  • software quality attributes
  • architecture analysis and recovery
  • architecture-driven design
  • agile architecture
  • design, architecture, and technical debt

(the official course syllabus is distributed via HEAT (SENG480a link))

Recommended/Required Text:

SEI Software Architecture in Practice, Len Bass, Paul Clements, Rick Kazman. 3rd Edition. 2013.

Other texts

  • Design It! From Programmer to Software Architect, by Michael Keeling, Pragmatic Programmers 2017.
  • Just Enough Software Architecture, by George Fairbanks, Marshall and Brainerd, 2010.
  • Documenting Software Architectures, by Paul Clements et al., Addison-Wesley, 2011.
  • Designing Software Architecture, A Practical Approach, by Humberto Cervantes and Rick Kazman, Addison-Wesley 2017.
  • Software Systems Architecture: Working with Stakeholders Using Viewpoints and Perspectives, by Nick Rosanski and Eoin Woods, Addison-Wesley, 2011.
  • Applied Software Architecture, Christine Hofmeister, Rod Nord, Dilip Soni, Addison-Wesley, 2000.
  • Essential Software Architecture, by Ian Gorton, Springer, 2011.
  • Software Architecture: Perspectives on an emerging discipline, Mary Shaw and David Garlan, Prentice-Hall, 1996.
  • Architecture of Open-Source Applications, Amy Brown and Greg Wilson, eds.

Past versions:


  • Neil Ernst, instructor. Office ECS 560, office hours Wed 11:30-12:30 & 2:30-3:30, or by appt.
  • Omar Elazhary, teaching assistant

Course Overview

After the course, students are able to:

  • begin to reason about and evaluate software design tradeoffs
  • capture software architecture in modern documentation approaches
  • work together in teams, with modern software tools.
  • use a views and beyond approach to capture software architecture.
  • compare and contrast different architectural styles, including product lines, microservices, MVC.
  • explain and recognise technical debt.


The class will use Github and Slack to work on the project. Students will have to register their Github username (either a permanent one or a throwaway) with the instructors. Those with an objection to using Github please contact the instructor for workarounds. All Github activity is private to the class organization. Please see the privacy notice on the Connex site.

Slack will be the primary mechanism used for communication in the class. My rationale (apart from being tools used in practice) is to expose the class as a whole to questions about projects, assignment, and lectures.

University and department policies on professional conduct and integrity are applicable. In particular, sexualized violence and harassment will not be tolerated. Feel free to see me in person, or via UVic email, for personal questions.


The final mark is weighted as following:

  • 15% assignment,
  • 25% midterm
  • 10% participation,
  • 50% substantial group project


Participation is worth 10% - demonstrated by:

  • activity on Slack,
  • contributions (and attendance, natch) in class.
  • Send Slack and Dr. Ernst a reading on software architecture and software comprehension. This can include blog posts, lengthy twitter chains, new books, Youtube videos, or podcasts.
  • Participate in the in-class exercise, optionally as part of the study.
  • Participation in the project is marked separately.

Assignment Undergrad

Undergrads: One individual assignment worth 15% of final mark. Due date as above.

For some project on Github, pick a quality attribute, create a (fully developed) quality attribute scenario, and document how the project source code realizes this scenario. Provide discussion on how the project can handle changes in this scenario in the future.

Details are in

Assignment Grad

Value: 15%. Due in class, and at end of term, as shown above.

Details are in

Group Project

The primary deliverable is a group project. You and your team will select a software project (OSS on Github/Bitbucket), and document important views on the software. The end result will be a set of documentation about the software system and a deep understanding of how it is constructed. 50% of final mark. Students will be assigned to teams and document an open source software system. Due dates in calendar above. See the Project outline.

Nota Bene: your individual mark in the project will be adjusted, possibly significantly, based on instructor assessment of your effort and peer reviews.


One midterm, worth 25%. Scheduled as above.


No final.