Todd Biske: Outside the Box

I was recently working on a presentation and putting together a diagram in Powerpoint, when it occurred to me that the diagram was quickly turning into something familiar, a UML Context Diagram. Why was this realization important enough that I decided to write a blog about it? Looking back through my career history, it’s not the diagram type I’ve used the most (that would be a sequence diagram), but it is the diagram that I’d say is the one I miss the most when it doesn’t exist.

A UML context diagram is really simple. You put one big oval in the middle that represents the entirety of the system that is going to be created/changed in the effort, and everything else that needs to interact with it is represented outside of the circle/oval with an annotated line indicating the interactions that happen.

There’s one simple reason why this is so important: boundaries. It immediately sets the context of what’s within the scope of the effort, and what isn’t. It makes it clear what data flows in and what data flows out. From an API perspective, the annotations on those lines are a great starting point for “jobs to be done” needed for solid API design following James Higginbotham’s ADDR process.

How many projects have you been on where boundaries like this haven’t been clear, resulting in significant time spent debating what’s in scope, what isn’t, who’s going to do the work, and who isn’t. While it is designed as a project artifact, it’s also very useful as a system artifact, clearly showing what those original boundaries were. Given how long systems stick around these days, preserving that information can be really valuable.

So, when you find yourself in cycles of endless meetings where it seems like the same things get hashed again and again, something it’s good to step back and provide a little context.