Series Recap: Narrative-Based Design is a software analysis and architecture process that I have developed and optimized over 20 years of experience in the field. It combines elements of object-oriented analysis, domain-driven design, n-tier architecture, service-oriented architecture (SOA), and data-centric principles, all tailored for an agile environment.
Based on my extensive experience and lessons learned, I have identified several key insights:
Agile development does not mean abandoning architecture; a pragmatic approach to agile can be highly effective.
Problem domain analysis, coupled with UML diagramming, can provide a deep understanding of both the problem and solution domains.
It is beneficial to perform a "Sprint Zero" before diving into sprints, where architectural and product requirement activities help clarify project requirements, mitigate risks, and prevent costly mistakes.
During our last blog post of this series - “Narrative Based Design - The (AI) Narrative”
We enlisted our buddy, ChatGPT to help us generate a comprehensive problem narrative for a Remote Learning Platform…
…which allows for interactive, synchronous, and asynchronous learning experiences. The platform should support multimedia content, have features for student collaboration, and incorporate assessment and feedback mechanisms.
To further define the requirements, we utilized ChatGPT to generate:
A robust problem or system narrative.
A list of actors, including students, teachers/instructors, administrators, parents/guardians, and IT support staff.
A use case landscape.
An epic landscape for system decomposition.
With the "WHAT" defined, let's delve into the architectural side of things and create diagrams that map the "WHAT" to the "HOW" of the solution.
Architecture & UML - A Lost Art??
UML diagramming may not be in the limelight, rarely mentioned in mainstream media or embraced by hyper-agile environments and startups. Nevertheless, it offers a robust set of diagram types that can fulfill most architectural needs. Here, we will focus on the following diagrams that have proven most useful over the years:
Use Case Diagram (or "Bubble Chart"): Clarifies the high-level scope, users/actors, use cases, and interactions between users and use cases.
Static Structure (Class Diagram): Provides a logical representation of the system's entities, clarifying vocabulary and fostering a deep comprehension of the system's nature and relationships.
Dynamic Diagramming - Sequence Diagram: Represents key interaction flows between a user and the system within a specific use case or workflow.
Logical Block Diagram: Illustrates functional blocks with a focus on system or subsystem boundaries and their interactions.
A couple of other diagrams I less frequently create, but which can provide significant value…
State Diagram - Depicts state machines, useful for describing system entities, workflows, and how they transition between predetermined states.
Activity Diagram - Utilized for systems with significant concurrent processes or threads requiring synchronization and serialized access to constrained resources.
By employing these diagrams, architects can effectively communicate and understand the system's architecture and behavior.
UML - Use Case Diagram - “The Bubble Chart”
Love, love, love this diagram. The Use Case Diagram, also known as the "Bubble Chart," serves as a bridge across stakeholder groups, providing a visual representation of the system's scope and usage.
Let’s diagram two (2) of the major use cases our buddy ChatGPT generated for us during the last blog post. We’ll decompose the use cases a bit and we will use Miro for diagramming using its UML shapes tool from Miro
(note: UML shapes in Miro are only available in their paid subscriptions - free subscription disables the UML shapes).
Use Case #1 (UC1) : Student Interaction with Online Content
Actor: Student
Description: The student (a) logs into the platform, (b) navigates to their current course, and (c) interacts with the online content. This could include (d) watching video lectures, (e) reading text materials
Use Case #2 (UC2): Instructor Course Creation and Management
Actor: Teacher/Instructor
Description: The instructor (a) logs into the platform and (b) uses the course management feature to (c) create a new course. They set the (d) course schedule, (e) upload educational content, and (f) assign homework tasks.
Let’s start our diagram by adding the two actors that span across the use cases, the Student and the Teacher.
Let’s now add use case bubbles for each granular use case in the first two use cases (UC1, UC2) defined above. Just drag the bubbles onto the canvas, as you hover over the actor icons or bubbles, you’ll see handles that you can grab to create lines between them.
By examining the diagram, it becomes evident that even with just two use cases, we were able to derive nearly a dozen granular use cases (represented as bubbles). This visual representation significantly simplifies the assessment of scope. Moreover, this diagram naturally aligns with feature definitions.
Furthermore, this diagram is an effective means of defining project phases and their corresponding scope, be it MVP, Phase I, Phase II, and so on. To indicate these phases, you can create a color legend and assign colors to the bubbles accordingly.
Another valuable aspect of this diagram is its ability to serve as a starting point for building a backlog of epics and coarse-grained user stories. For instance, implementing the "View Courses" use case (UC1b) would require a Course Catalog UI, a course catalog data store, and/or a course catalog API. An example user story could be, "As a student, I want to view my courses."
This diagram provides a holistic view of the system, facilitates feature prioritization, and guides the creation of user stories and backlog items.
UML - Static Structure Diagram
The Static Structure Diagram is an invaluable tool for software architects and engineers seeking a deep understanding of the problem and solution domain. This diagram serves as a logical entity model and should not delve into specific technologies, operating systems, or cloud platforms. Its purpose is to represent the entity landscape of the domain accurately.
To begin constructing this diagram, I recommend reviewing the problem or system narrative and extracting the nouns or entities. These entities can be placed on the canvas using the "Class" UML shape.
During the initial pass of creating the logical model or static structure, it's best not to get caught up in strict UML semantics, such as class attributes/methods, cardinality, composition, and aggregation. Especially when there's ambiguity in the domain, it's more important to use simple class names that align with the common vocabulary used by product designers and the business to describe these entities.
I highly recommend adding text on the lines connecting entities. This text should describe the nature of the relationship, and an arrowhead can indicate the direction in which it should be read. For instance, in the diagram, we can infer relationships such as:
A Course Catalog has multiple Courses
A Course Manager can create new Courses
A Course has a set of Course Content Materials
A Video Lecture is a video form of Course Content
By creating this diagram, you can efficiently ramp up on a new problem domain, understand the landscape, and establish a common vocabulary among stakeholders. It's essential to address any discrepancies early on, such as when different departments refer to the "Course Catalog" as a "Register." These differences may indicate alternate names for the same entity or nuanced yet important distinctions that might require adding a "Register" entity to the model.
As you iterate on this diagram, you'll easily identify gaps and inconsistencies. It also presents an opportunity to establish a shared vocabulary for all stakeholders regarding the key entities of the system. Once you gain a level of comfort and confidence that the diagram accurately reflects reality, you can enhance it with a more rigorous UML representation. This includes incorporating entity attributes and methods, common OOD concepts like inheritance, aggregation, and composition, as well as additional context such as cardinality and ordinal numbers.
At this stage, it's often helpful to create a Logical Block diagram or additional UML diagrams like Package or Deployment diagrams to round out the initial set of architectural views encompassing the scope, use cases, and entity landscape.
UML - Sequence Diagram
After using the use case diagram to represent scope and the static structure diagram to depict the entity landscape and relationships, it's time to explore the dynamic aspects through a diagram that captures key interaction sequences and workflows.
The UML sequence diagram is the most popular and useful diagram for this purpose. It illustrates the flow of interactions from the actor (user) through subsystems and/or entities as a sequence of messages or method invocations.
Similar to the Static Structure diagram, we enlist the entities and/or subsystems defined in our previous use cases, which become our "Classifiers" represented as rectangles (highlighted in green below). We connect them using lines or "Activation" shapes (long skinny rectangles) that hang off the classifier boxes. These activations represent the passage of time or causal relationships, where time increases as you move down the diagram. To enhance clarity, it's beneficial to use bounding rectangles to highlight and organize key sub-flows within the diagram
In this discussion, we'll focus on the core aspects that are essential for effective communication with stakeholders, leaving out the UML semanticsor what my undergrad OOP professor used to call “syntactic sugar” (shout out to Dr. Paul Krasucki - Rutgers University) . The goal is to convey the problem, the process, or the proposed solution in a simple and effective manner.
By examining the sequence diagram provided, you can grasp the high-level flow and subsystem interactions involved in three major use case sub-flows:
Auto-login a user
View Course Catalog
View My Courses
This sequence diagram effectively communicates the overall flow and interactions between subsystems, aiding stakeholders in understanding the dynamic behavior of the system in relation to these use case sub-flows.
Summary & Final Thoughts
In this blog post, we dove into the world of Narrative-Based Design, a software analysis and architecture process that I've refined over my career.
We kicked things off by debunking the myth that going agile means abandoning architecture. Quite the opposite! With a pragmatic view of agile, architecture can play a vital role in successful software development.
We then explored the power of problem domain analysis and UML diagramming. By focusing on use case diagrams, static structure diagrams, sequence diagrams, and more, we discovered how these visual representations can provide a deep understanding of both the problem and solution domains. These diagrams help us clarify project requirements, assess scope, and foster a common vocabulary among stakeholders.
Throughout the post, we emphasized the value of these diagrams in guiding architecture decisions, defining project phases, creating backlogs, and ensuring a clear understanding of the system's entities, relationships, and dynamic behaviors.
While UML diagramming may not be the talk of the town, it remains a powerful and often underutilized tool in our architectural arsenal. By leveraging its various diagram types, we can communicate complex ideas, align stakeholders, and build solid software solutions.
Thanks for joining me on this journey through Narrative-Based Design and the world of UML diagramming. Feel free to share this post with others who might find it helpful in their software endeavors.
Happy coding!
REFERENCES
Books:
"Domain-Driven Design: Tackling Complexity in the Heart of Software" by Eric Evans
"Applying UML and Patterns: An Introduction to Object-Oriented Analysis and Design and Iterative Development" by Craig Larman
"Agile Software Development: Principles, Patterns, and Practices" by Robert C. Martin
Websites and Blogs:
Martin Fowler's website: https://martinfowler.com/
UML official website: https://www.uml.org/
DZone: https://dzone.com/
InfoQ: https://www.infoq.com/
Agile Methodologies:
Agile Alliance: https://www.agilealliance.org/
Scaled Agile Framework (SAFe): https://www.scaledagileframework.com/
Software Architecture:
Software Engineering Institute (SEI): https://www.sei.cmu.edu/architecture/
IEEE Software Architecture: https://www.computer.org/csdl/magazine/software/