⚡ TL;DR
- Understand who your audience is and what they want to know about your software systems.
- Define the story you want to tell based on your audience and needs.
- Keep things simple. Diagrams should have the right level of detail to convey your story.
- Label objects and connections clearly. Avoid acronyms or adjust based on the C4 level.
- Take advantage of IcePanel’s model-based system to create reusable objects.
🧊 Introduction
Diagrams are only useful if your audience can understand them. Since we started IcePanel 4 years ago, we’ve supported countless teams to help them create engaging diagrams using the C4 model. In this article, we’ll share 5 simple tips to help you craft effective diagrams. Let’s get started! 🏃
🫂 Tip 1: Understand your audience
Before creating a new diagram, it’s best to start by understanding who your audience is. Are you communicating with executives, business stakeholders, other architects, engineers, DevOps, or your Mom? Different people will care about different things, which means your diagrams should be tailored accordingly.
Business stakeholders might care about the high-level architecture and things like 3rd party dependencies from a cost perspective. Engineers might want to know more about logical relationships and the system’s structure (e.g., what the different microservices are and how they interact with one another). DevOps engineers will want to know the deployment details. Your Mom just wants to know you’re doing okay and how smart you are.
Breaking this down in as much detail as possible is critical. For example, let’s say you’re working on an e-commerce system with a microservice architecture as a lead engineer on the Returns team. You’re working on a project introducing new functionality dependent on several teams, such as the Checkout and Payments team. Knowing this, you can focus on the specific service dependencies other teams will need to be involved in for your solution.
📖 Tip 2: Think about the story you want to tell
It might sound obvious to say, but it’s important to think about what you want to communicate before even starting to diagram. Confusing diagrams are often rooted in ineffective storytelling. Good diagrams tell focused stories to a specific audience.
A useful resource on storytelling is Pixar’s 22 Rules of Storytelling, originally shared by former Pixar employee Emma Coats. Although not all of the rules directly apply to software diagramming (we’re not creating fiction after all… or are we?), there are many parallels.
Some useful ones to call out are:
- You have to keep in mind what’s interesting to you as an audience, not what’s fun to do as a writer (in this case, architect or engineer). They can be very different.
- Why must you tell this story? What’s the belief burning within you that your story feeds off of? That’s the heart of it. (In the context of software architecture, what decision or outcome are you aiming for from the diagram?)
- What’s the essence of your story? The most economical telling of it? If you know that, you can build out from there.
Writing down a few sentences to define your story can have a huge impact later on. It’ll also make it easier once you’re ready to start diagramming and help guide which level in the C4 model to focus on. We recommend following a simple format, taking inspiration from the jobs-to-be-done framework.
As a (audience), I want to (goal), so that I can (outcome).
Example: As an engineer on the Returns team, I want to communicate the dependencies between the Returns, Checkout, and Payments teams so that we can plan appropriate changes for our new feature.
😖 Tip 3: Don’t overcomplicate things
A common mistake is including too much detail in a single diagram. There’s a natural tendency to want to ‘show everything’ because that’s what reality is-it’s messy. Although this may be with good intent, spaghetti diagrams rarely provide much value. They usually have the opposite effect and make people less enthused about engaging with documentation.
In practice, it’s best to focus on something specific in each diagram-whether that’s a logical view or deployment details. Avoid showing too many views and instead create multiple smaller diagrams. If you have multiple teams that own separate product areas and microservices, use IcePanel’s domains feature to organize diagrams more neatly.
In a recent talk, Simon Brown recommended showing only apps of a specific system in a Level 2 diagram and avoiding showing apps belonging to other systems. Doing so makes team boundaries and ownership more ambiguous, leading to ‘coupling’ of ownership. We recommend this advice as well, but depending on what you’re trying to communicate, there may be situations to show app relationships across systems.
🏷️ Tip 4: Label objects clearly
Labelling things properly goes a long way toward making diagrams understandable. We can’t stress this enough. Clear, simple names and descriptions immediately help people understand things. It’s worth the initial effort.
Here are some quick tips when it comes to labelling:
- Label objects and connections (sorry, not sorry, for being repetitive). Unlabelled items make it impossible to know what the object or relationship is, leading people to ask for clarification (which defeats the purpose of documentation in the first place).
- Name objects in an accessible way and avoid acronyms. Put yourself in the shoes of a new team member, and name things in a way they can understand with little to ideally no explanation.
- Add short descriptions to objects. 120 characters is all it takes to give some context on what an object does to reduce the explanation needed even further.
🔋 Tip 5: Leverage the power of the model
On the surface, IcePanel seems like just another diagramming tool, but it’s much more. It’s a model-based tool, first and foremost, allowing you to define a single source of truth to create different views. Make sure to leverage the model once you have created an initial foundation.
Some quick tips on getting the most out of the model:
- Double-clicking in the canvas exposes an object search. Before creating a new object, see if it already exists to avoid duplicates. It’s sometimes helpful to define an initial set of objects with your team so everyone is on the same page.
- Add technology choices, tags, and up-to-date statuses on objects so you can use the tag bar to show different perspectives. It’s also helpful to define an initial set of tag groups with your team when first starting (e.g., things like cost, region, or deployment details).
- Use the Dependency View to see how intertwined an object is in your architecture before making changes.
🏁 To wrap up
Following these 5 tips will help you create diagrams that your audience will understand and engage with. Think about your audience to craft a compelling story, and take the time to fill out relevant details. A little upfront effort will go a long way. IcePanel’s model-based system means you have to do less maintenance in the long term as your architecture evolves.
