How Diagrams Unlock the Complexity in Simple Systems

Slack looks simple. Just a chat app dressed up in pretty packaging. Internet relay chat (IRC) has been around for 30 years, so anyone could put together a clone in a few days, right? As a software engineer you're probably already rolling your eyes.

Matt Haughey, founder of MetaFilter and editor at Slack, recently debunked this common sentiment:
Image 1
(Source: Twitter)

The 8k retweets and 13k likes show this struck a chord. Slack looks simple because the engineering team has gone to great lengths to hide the underlying complexity from the end user. The engineer gets complexity, the user gets simplicity.

This is a great insight into how software complexity is hidden. But it is an even greater insight into how diagrams can help engineers be better understood by their own team, other teams in the company, and the wider world.

Beside dealing with errant HN commenters, users don't normally need to see how the sausage is made. But the rest of your team do. If engineers are building features that the marketing or sales teams can't understand, they'll have trouble communicating the true worth to the outside world.

Software engineers can help their teams and their customers understand complexity with visual communication through diagramming.

21,585 people were able to understand how incredibly complex the Slack notification system is from a single tweet. The same thing can help your team understand your product's complexity as well.

The conservation of complexity

When at Xerox PARC, computer scientist Larry Tesler, the man behind the Apple Newton, developed what has become known as Tesler's Law of Conservation of Complexity:

“Every application must have an inherent amount of irreducible complexity. The only question is who will have to deal with it.”

In earlier software, the user would deal with it. To use IRC as an example, ircII, the earliest IRC application still being updated, is command-line based. No GUI, no tabs, no nothing. To join a new channel, you need to open a new shell. It's a powerful chat app, but it isn't simple to use. The user needs to know what they are doing to master it.

Image 2
You still get /help, but no /giphy with ircII. (Source: Linuxaria)

But with design and UX taking a stronger role in software development, complexity is now more likely pushed to engineers. As Tesler describes it, this is how it should be:

If a million users each waste a minute a day dealing with complexity that an engineer could have eliminated in a week by making the software a little more complex, you are penalizing the user to make the engineer's job easier.

This produces a challenge for developers. Not only are applications becoming increasingly complex, but this increasing complexity has to be increasingly hidden from users.

This causes the nasty side-effect the team at Slack sees so often. By hiding complexity, people presume it's not there. It looks simple, thus must be so. This creates a disconnect between technical and non-technical teams within the company. As complexity increases and becomes increasingly hidden, it becomes more difficult for the rest of your team to understand the mechanics of the product. All teams can suffer:

    • If they don't understand the product, your executive team might ask for features that aren't feasible or will break current features. Obligatory xkcd cartoon:


  • Without knowledge of how the product works, your marketing team can't produce worthwhile content to support it, nor identify the right users to target.
  • This is also true for the sales team. Without understanding, they won't be able to talk to prospective customers about why the product is so powerful.
  • Your support team will be hard hit by lack of expertise. Any support issues will have to be dealt with by members of the technical team.
  • Finally, your engineering team suffers because they will be called upon constantly to help the support, marketing, and sales teams.

Even within product teams, Product managers might start to struggle with the underlying structure of what their own team are building. This means they can't do their job properly. There are two ways around this problem:

    • 1. Hire people with technical backgrounds in all roles. This is inefficient—you'll end up paying more money for people who are less good at their primary job.


    2. Teach your teams the complexity.

The second option might seem overwhelmingly difficult, but we've already seen it being done perfectly in Matt's tweet. He taught 21k people how notifications work in Slack with one single diagram.

From complexity to simplicity in one hundred easy steps

By diagramming decision, data, and user flows, engineers can easily communicate how the product works to the rest of the team.

Slack is a prime example of Tesler's law. It has irreducible complexity. Teams, channels, notifications, bitmoji—each make the app better for the user, but add a further layer of difficulty. Slack is choosing to keep this complexity under the hood, putting the emphasis on engineers rather than end users.

This is clear from the notification flow in Haughey's tweet:
Image 4
(Source: Reducing Slack’s memory footprint)

This is all the logic the server has to deal with when you @-mention someone in Slack and hit enter. One simple act for a user, one complex problem for an engineer, and one vital process for the success of Slack.

The developers at Slack may know how this works, but no-one else will until it is explained. The complexity of something so seemingly simple presents a disconnect between the internal teams. Imagine a member of the Slack engineering team verbally explaining that flow to support team members to help them deal with notification issues:

When deciding whether we should send a notification, we first check whether the channel is muted. If it is, we then look at whether this is a threaded message and the user is subscribed to the thread. If these conditions are both false, we don't send the notification. If both these conditions are true, or if the channel wasn't muted to start with, we'll check whether the user is currently in Do Not Disturb mode. If they are, we'll see whether the sender wants to override. If they don't, the notification won't be sent. If they aren't in Do Not Disturb mode or the sender wants to override, we'll check whether the mention is global, then...

By this point the support rep is either snoozing or completely lost, and they've only covered this much:
Image 5

100+ words in and we're still only at the top of the diagram. Even if an engineer could describe it all, the rep would never be able to process it all, unless they had a good understanding of logic and an immense memory.

This is why they have chosen diagramming as the best option for understandability. It not only shows the underlying complexity, it also teaches the underlying complexity. That is what is so vital for the rest of the team. In one glance, they can understand how an incredibly complex part of the Slack protocol works, and use this information in their role:

  • If the executive team want to add more features, they can understand where it fits in the existing workflow.
  • When the marketing team are promoting new features (such as conversation threads), they know how they work with notifications.
  • The sales team can talk expertly about notification features if it comes up with a prospect.
  • The support team can walk users through the flow if they are in trouble.
  • The engineering team can build.

What looks simple but is actually complex becomes simple again with this visualization. If there are diagrams like this for all Slack features, the entire team can understand the entire product.

This has an added bonus that becomes clear if you read through that tweet thread. Some people found this loop at the bottom confusing:
Image 6
Haughey explained that this delay loop was to prevent users getting simultaneous notifications from the Slack desktop app and their mobile app. Not only do the Slack team understand this now, but also the thousands reading that tweet. Everyone understands the complexity in simple terms.

From complexity to simplicity in a single step

Will the notification system for Slack look the same in a year? Probably not. New features will be added making it even more complex. But because the team diagrams out the process, it will still be understandable for everyone.

The same can be true of your product. If you are doing the right thing and making your app simple for users, you are probably moving the complexity burden underneath. This makes it more difficult for your team to understand.

Diagramming removes that block. Simple diagrams like this will not only help your engineering team understand their own builds, but help every single other person in your organization understand them as well. This isn't just an intellectual exercise—it will actively help them do their jobs better.

Plus, when someone on Reddit says they can build your app in a day, you'll have something to show them.