Sequence diagrams and the types of work enabling agile delivery

Two weeks ago I made a post which I then realised needs to be elaborated upon.

? I said it once, I'll say it again and I'll never stop ?? - Sequence diagrams are the single most important tool to visualise your software, your dependencies between teams and departments, the collaboration within your organisation, dependencies between software packages, your production and manufacturing flow etc.

? If you cannot represent a feature with a sequence diagram, you just don't understand it enough yet. The inverse is also true - if you CAN represent your feature, architecture, organisation, ... with a sequence diagram, that means you have it figured out pretty well.

? And don't think for a second that sequence diagrams are only for parallel software services talking with messages. They can be used to visualise any set of asynchronously dependent entities exchanging any information, data, documents, physical artifacts. You can use them to visualise entire manufacturing operations and supply chains.

Value stream mapping is just a specialised version of a sequence diagram!

? Oh and here's the kicker - when you are working on an agile team and want to prepare a good breakdown of work "how to deliver a software product", focus on creating sequence diagrams for all features, and translate the sequence diagrams into user stories in a backlog. Done! Now you can implement the flows, test them, package and deploy them independently. ? ?

? Understanding sequence diagrams and using them for work breakdown will give you superpowers and turn your team into laser falcon tiger dragons!

And here are my additional thoughts which cannot fit in a single post.

Sequence diagrams visualise interactions between independent entities, executing their functionality in parallel, and asynchronously exchanging information.

This way of describing and visualising components of a system is very close to the original idea of objects introduced by Alan Kay. Modern object oriented programming is a direct violation of the model originally proposed by Alan Kay. It was never about objects or references, it was rather about asynchrony, by-value messages, requests and locality. You couldn't do things "by-reference". What Alan Kay (and those before him) was describing so many years ago was a micro-service oriented way of designing systems. Just look at the Smalltalk object orientation. It is much closer to what Erlang has today. Ok, back to sequence diagrams.

I base all my project work, work breakdown structures, backlogs on a design achieved through the exercise of creating sequence diagrams for all the components, and all the entities in the complex systems I create.

Sequence diagrams are not only useful for software design. They are based on very simple principles, where parallel entities and their actions, and the message exchanges triggering these actions are very generic.

You can use sequence diagrams to represent a process of baking an apple pie, the interactions of the whole kitchen staff, the logistics network supplying the ingredients, or the software programs enabling this flow. Each time you represent your systems with a sequence diagram you gain a much deeper understanding of what needs to be done and how.

The best part - there is no situation which cannot be represented and simplified with a sequence diagram.

Don't get me wrong, there are situations where creation of a sequence diagrams, is a difficult, time consuming and a frustrating exercise. This is however not due to the sequence diagrams themselves, rather due to the overly complicated, overly interconnected, non-local, distributed, unknown or mismanaged nature of the projects you need to visualise. And persevering through the pain of actually creating sequence diagrams, and having them represent reality, will always bring you benefits outweighing the efforts.

The ability to create a sequence diagram of your software, your integration pipeline, your organisation, is a litmus test if you understand any of them.

Having this understanding, we are empowered to realise there are three (3) and only three types of work we need to manage for any engineering project.

These are

1. the implementations of sequential flow,
2. the modification, improvement, extensions of existing flow,
3. and the architectural work (just enough architecture) enabling both.

In short I call these

• flow stories (work items),
• improvements or bugs,
• and architectural stories (work items).

They are all connected to concrete and specific messages and actions in one specific sequence diagram, a subset of a diagram. Always.

I postulate all engineering work - or any work for that matter - can and should be represented, tracked and managed, using these three types of work. Further I would argue that all other types of work are just over complications, derivations or variations on these three e.g.

• epics - big flow stories - sequence diagrams representing a bigger slice of vertical integration of some feature,
• user stories - flow stories - sections of a vertical integration represented by a bigger sequence diagram,
• test - architectural stories - enabling the appropriate testing and verification of a flow,
• interrupts - improvement or bug fixes for an existing flow.

Note that sometimes the engineers, the managers, the architects will themselves not understand what the sequential diagram of the whole system, or their subset of the system is or should be. This is proving my point.

Another good example is an implementation of some software service. Software is typically expressed through use cases. What are use cases? They are textual descriptions of interactions between the customer and the customer facing parts of the solution, focused on providing measurable value.

If expressed visually, with added time domain (axis), with a little more careful and rigorous representation of entities and data passed between them, we get a sequence diagram for each use case.

In another article I mentioned four (4) other types of diagrams which provide value to all stakeholders: dependency (stack) diagram, entity diagram, data flow diagram and value stream map.

All these listed types are just a sequence diagram through a different lens, simplified and emphasising different aspect of the design.

• Dependency (stack) diagram removes the time domain and the details of entity relationships to focus only on showing the entities themselves, with high level connection descriptions.
• Entity diagram is like a dependency diagram, but adds more detail to the relationships between entities, and the core data they use. It is like an empowered class relationship diagram.
• Data flow diagram is a sequence diagram, but assuming a single entity and no asynchrony. All actions and all data depends on each other sequentially. This is for example how functional programming languages are designed, with their pure functions and immutable data paradigms.
• Value stream map is a sequence diagram drawn for the value stream of your organisation. It adds additional information on the timing of each action i.e. lead time, cycle time, throughput. With VSM you gain the visibility of the real performance of your organisation, and can benefit from awesome tools like the theory of constraints.

I hope you recognize how all these methods of visualisation are just variations on a common theme.

Breakdown of software into deliverables doesn’t need to be difficult. Aligning architecture work with a backlog of valuable deliverables also don’t need to be difficult. What you need is a technique to understand dependencies through time, and decompose. Sequence diagrams give you just that.

The key to designing good software is understanding how the data is flowing through your application. Inputs, transformations, outputs - this is what functional languages like #Clojure enable. We get good design through the application of the theory of constraints to software engineering.

If you found this article enjoyable and informative, please continue reading other articles in this newsletter.

#valuequoted #softwareengineering #management #ceo #cto #agile #lean #toc