Using UML vs. ADL (Arbitrary Diagramming Language)

At my company, we highly encourage our architects and developers to communicate their design models through UML.  We have a standard set of diagrams that we regularly use to convey aspects of a given solution, including:

  • Component diagrams for system dependency, functional decomposition and data flow
  • Use case diagrams for business and system scenarios
  • Sequence diagrams for a timing perspective on system interactions
  • Deployment diagrams for both logical and physical representations of the hardware/software landscape

We all know that the job of architect pretty much consists of “ask lots of annoying questions” and “draw boxes and lines.”  The downside with being so UML-centric is that UML can accidentally become the default way to draw boxes and lines that represent all sorts of things.  My boss has encouraged us to be observant for when a particular graphical representation should take a more “marketecture” approach (i.e. fancy boxes and lines in PowerPoint or Visio) vs. formal modeling in UML or BPMN.  She labeled the PowerPoint/Visio approach as using the Arbitrary Diagramming Language (ADL) method.  Seems about right.

What’s an example of this?  I’ll give you two.  I recently had to put together a reference architecture for a project I’m working on.  My first inclination was to throw together a functional decomposition diagram (component diagram) of all the relevant functional pieces.  However, this was very early in the project lifecycle, and I knew that this diagram would be consistently referred to in both business and technical meetings.  So instead of going nuts on a UML diagram that would be utterly confusing, and potentially hacked up to represent certain ideas, I went with a PowerPoint model that has been in regular use for 5 months now.

In another case, I’m trying to represent deployment options (incremental phased approach vs. all-at-once) for a global system.  I began this effort thinking about component diagrams, deployment diagrams, swim lanes and mashing some things together.  Again though, I’d probably have to bastardize UML and overload agreed-upon constructs in order to convey my point.  So, I went again to trusty PowerPoint and modeled out the options in a more business-friendly way.  I could create my own terminology/model without feeling guilty for screwing up standard UML.

This way, I could convey a sequence of deployment phases (through a set of slides), which parties were involved, and the necessary interim interfaces without butchering UML.

So when to use each modeling style?  I’d like your thoughts as well, but for me, I switch to an ADL / marketecture model when:

  • Doing early project stage diagrams to convey concepts presented to broad audiences (e.g. logical architectures, deployment diagrams, proposed data flow between systems/organizations)
  • I realize that I need to cannibalize, bastardize, overload or otherwise distort UML notation to convey a point (e.g. user experience flow, etc)

I fire up a UML tool for modeling when:

  • I’m building lasting representations of how a system will be built and providing an accurate blueprint to the development team
  • Conveying solution aspects to solely technical teams through presentations or design documents
  • I can take a particular solution aspect and clearly convey the point via one or many complimentary UML model perspectives.

The hard part is not stuffing so much into a single visual model as to render it useless.  There’s no shame in requiring two (or more) different perspectives on a problem.

So there you go. Is Visio/PowerPoint/other-boxes-and-lines-tool-of-choice your first place to go when you have to diagram something for your project team or management?  Or do you try and shape and morph traditional diagramming notations to fit your needs?

Author: Richard Seroter

Richard Seroter is Director of Developer Relations and Outbound Product Management at Google Cloud. He’s also an instructor at Pluralsight, a frequent public speaker, the author of multiple books on software design and development, and a former editor plus former 12-time Microsoft MVP for cloud. As Director of Developer Relations and Outbound Product Management, Richard leads an organization of Google Cloud developer advocates, engineers, platform builders, and outbound product managers that help customers find success in their cloud journey. Richard maintains a regularly updated blog on topics of architecture and solution design and can be found on Twitter as @rseroter.

7 thoughts

  1. I agree that Visio and PPT’s are the best way to communicate with the business. Nice to see it in writing from a member of the Architecture team too.

  2. Great article Richard. I always thought that PPTs are best suited to explain complex diagrams using simple animation techniques and layering which will take the audience from a simple rectangle (or similar) to the complex architecture diagram… just like if I were to explain this in a drawing board.
    Thanks for sharing your thought.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.