Use this chapter to describe what happens behind the interfaces when a user or an external system interacts with your architecture’s touch points.

Pick scenarios that work well for illuminating the design. Don’t feel you have to illustrate every single flow, just the architecturally significant areas.

While I have never doubted that UML sequence diagrams is the right choice for describing behavior, I have been avoiding them because they are notoriously cumbersome to draw. It always starts out fine, but halfway through the diagram I realize that I have forgotten something, which I need to insert, and then the whole layout gets scrambled, and I end up spending too much time tweaking the layout rather than focusing on the content.

But recently, a colleague recommended that I check out a free online UML sequence diagramming editor, which draws the diagram for you based on simple textual descriptions of the sequence. It’s called PlantUML, and to use it more efficiently I have developed my own wrapper app, editor.