Documenting Your Product – Part 3 – Sequence Diagrams

This is the third in a series of posts about documenting technology product builds. If you missed the intro, Part 1 – Use Cases, or Part 2 – Requirements, go check them out. At the end of this series, I’ll be providing a bunch of templates and resources to make this process more manageable.

For this series, we’re building a product called PetSitPro, which matches pet sitters with pets in need of pet sitting. As a refresher, a Pet Sitter is someone who provides pet care, and a Pet Parent is someone who has a pet to take care of.

In this post, we’re tackling sequence diagrams. I’ve fallen in love with using sequence diagrams over the last couple of years as a way to map complex systems and the specific interactions between components within those systems. Whether you’re building monolith or micro-service based applications, sequence diagrams allow you to see exactly what it is that you’re trying to build.

What are Sequence Diagrams?

In simple form, sequence diagrams are akin to flowcharts. Their purpose is to visually illustrate a system interaction in as much detail as possible, showing what data is going back and forth. Here’s a really simple example that shows how you might illustrate a Pet Parent might search for a Pet Sitter, find one and book them.

Pretty simple right? It shows the entire interaction including the payments processing and all of the actors involved. This is a “success case” where the payment was successfully processed.  What happens if the payment fails? It might look something like this:

You can see how complex it can get with just this seemingly trivial use case (remember use cases?).  With sequence diagrams, you can get into all sorts of fun around system boundaries, loops, asynchronous interactions and lots of other goodies. These two examples are very basic.

For illustrating how you want a system to behave, it’s far more effective than using a traditional flow chart because it forces you to define clearly what components are responsible for each part of an interaction.

Where Do You Start?

I’ve used a number of sequence diagram tools over the years, but I really only use two now:

• PlantUML is free and has really solid documentation and examples. Once you’ve read through those you can click here to build your first diagram.
• WebSequenceDiagrams is a good bit more flexible. They’ve got a number of different styles and they have a decent library feature where you can store and organize your diagrams if you use the paid version.

I suggest you try both and see which you like better. The sequence diagram syntax is close to the same, but not exactly the same, for each tool.  Speaking of syntax, you can view the source for each of the diagrams above (created on PlantUML) at the end of this article.

I hope you dig in and start using sequence diagrams. They really do force you to think through all of the system components and their interactions and will expose gaps in your design that may save you precious time and money.

Next up in this series we’ll talk about documenting data models. See you next time!

Sequence Diagram Source

Success Diagram

@startuml
participant PetParent
participant PetSitPro
participant Payments
participant PetSitter

PetParent -> PetSitPro: Find \n Pet Sitter
PetSitPro -> PetParent: Results
PetParent -> PetSitPro: Book \n PetSitter
PetSitPro -> Payments: Process \n Booking \n Payment
Payments -> PetSitPro: Payment \n Confirmation
PetSitPro -> PetParent: Send \n Booking \n Confirmation
PetSitPro -> PetSitter: Notify PetSitter
PetSitter -> PetSitPro: Accept Booking
@enduml

Failure Diagram

@startuml
participant PetParent
participant PetSitPro
participant Payments
participant PetSitter

PetParent -> PetSitPro: Find \n Pet Sitter
PetSitPro -> PetParent: Results
PetParent -> PetSitPro: Book \n PetSitter
PetSitPro -> Payments: Process \n Booking \n Payment
Payments -> PetSitPro: Payment \n Fails
PetSitPro -> PetParent: Ask for \n different card
PetParent -> PetSitPro: Enter New Card
PetSitPro -> Payments: Process \n Booking \n Payment
PetSitPro -> PetParent: Send \n Booking \n Confirmation
PetSitPro -> PetSitter: Notify PetSitter
PetSitter -> PetSitPro: Accept Booking
@enduml