The features I look for in a technical diagram

I’ve seen so much variance on this in reviewing designs for software systems that it would be good to have a reference to point to of what I like to see and why I think it’s beneficial.

What diagram type should I chose? component or sequence?

morpheus combine them

The value a sequence diagram provides is to show both space and time, as concurrency of requests is very important in software protocol design.The value of a component diagram is showing the ontology of the system.

To combine them, we can simply number each arrow in a component diagram.

Detail the relationship cardinality

The icing on this cake is to collapse yet another dimension: “Cardinality” into the diagram using Crow’s foot notation. This allows us to show what the relationship of each “entity” in the diagram should be, e.g. 1-to-many but the inverse could be simply only-1 or zero-to-1.

Generate the diagrams from text

Here’s an example illustrating all this using my favourite diagramming tool PlantUML. (Entity Diagrams - PlantUML) It’s my favourite tool as you can quickly modify or maintain a complex diagram by making very small changes to a text file. Additionally it’s open-source meaning if you’re diagramming sensitive intellectual-property you don’t have to worry about it being stored by some other system.

I didn’t want to make the example trite or stupid so I’ve kept it generic, but this wouldn’t be an unusual diagram for some sort of web authentication flow or something.


entity "entity A" as A
package foo {
  class "entity B" as B
  class "entity C" as C
entity "entity D" as D

A }o--> B: 1. Makes request to B for access
B --> C: 2. checks if this is ok?
C --> A: 3. asks A for information
A --> C: 4. A responds with request
C ||--> D: 5. C forwards info to D 


which results in a diagram like this


Walking through the nice features we have in the above diagram

  1. Time: thanks to the numbering we can follow the order of operation
  2. Hierarchy and ownership: entity B and C are in the same grouping “foo”
  3. Cardinality: there can be zero-or-more connections to B, and there is one-and-only-1 connection to D for C

There’s one thing I did not capture here which is a slight limitation on either PlantUML system or my knowledge of it. You can’t combine the crow-feet technique with an additional arrow on the connector to indicate the flow of data. The arrows in the above diagram are just a duplication of the numbering scheme.