Flow charts are O(n)2 complex, so don't go over 100 connections

Flowchart design is a game of balance: Read about the importance of dialling in the right level of detail and how to manage complexity in large flowcharts.

Flow charts are O(n)2 complex, so don’t go over 100 connections #

In the book The Phoenix Project, a novelization explaining some of the core principles of DevOps, the authors write that: “One of the defining characteristics of a complex system is that it defies any single person’s ability to see the system as a whole and understand how all the pieces fit together.” Understanding a system is one challenge, as they say, but explaining a system to another person, especially an outsider, is even harder.

This is often the challenge developers face when writing documentation because documentation tends to rely heavily on text. Documentation tends to rely on text, but as effective as text is for explaining details, text often fails to evoke the big picture. When you’re explaining a complex system, readers need to not only understand the components of the system, but the flow across components, the process that turns components into an application.

Enter flowcharts.

Flowcharts are an old tool, used in many industries and for many different kinds of processes and systems, but they’re essential to software documentation. With flowcharts, you can provide readers with a visual representation of the system in question, giving them the chance to integrate the more granular details they’ve been reading about into a coherent whole.

It’s a simple idea that’s surprisingly difficult to do well. Overly complex flowcharts fail to be successful flowcharts because they provide you with so many details that the larger meaning becomes obscure. Overly simplistic flowcharts look like fluff, providing a semblance of meaning without any useful information.

In this article, we’re going to explain why flowcharts can drift toward complexity or simplicity and show how you can ensure your flowcharts are as effective as possible.

Purpose of flowcharts #

The primary purpose of flowcharts is to show the steps in a process and the flow between steps so that readers can understand the process as a whole. You can get more or less granular with flowcharts, but the purpose remains.

Flowcharts are versatile and generic #

Flowcharts are used across industries and across many different types of processes – none of which necessarily have bearing on the resulting complexity.

The software development life cycle, for example, is often illustrated through a very simple flowchart despite the steps involved being complex.

An illustration of the Software Development cycle.

Meanwhile, Vogue produced a much more complex flowchart to help people clean out their closet.

An illustration of a closet cleaning workflow.

Of course, you could imagine a software development life cycle flowchart that is much more complex and a closet cleaning flowchart that is much simpler. The point is that flowcharts are eminently versatile, meaning you can use them across domains and zoom in and out with complexity and detail. When designing flowcharts, the first fundamental step is to focus on what your flowchart needs to do and abandon assumptions about what flowcharts are supposed to look like.

Flowcharts fail when they’re too complex or too simple #

The irony of flowchart design is that they’re meant to combat the complexity that comes with detailed, comprehensive documentation, but flowcharts themselves tend to be messy and overly complex.

Back in 2018, a flowchart from the Pentagon went viral because it reached an absurd level of complexity.

An illustration of a complex flow chart.

This is an extreme example, but it illustrates the point: When a flowchart is too complex, it fails to achieve its purpose.

That said, simplicity can be ineffective too. If a flowchart is too abstract, it won’t communicate anything useful. Worse, it can communicate something else: The impression that the rest of your documentation is similarly meaningless.

Images and diagrams are a double-edged sword. They can be attention-grabbing, but if they grab the reader’s attention and then provide them with fluff, the reader can lose faith. A Nielsen Norman Group study shows that “users pay attention to information-carrying images that show content that’s relevant to the task at hand,” which is a great opportunity. But the study goes on to say that “users ignore purely decorative images that don’t add real content to the page.”

Flowcharts need to communicate that they’re meaningful and to do that, they need to balance complexity and simplicity.

Where good flowcharts go bad #

There’s no such thing as a perfect flowchart nor a universal standard for how many nodes and edges are best. One bad flowchart can be too simple – imagine one with only two steps – and another can be too complex – refer to the example from the Pentagon.

A good flowchart is somewhere in the middle – zooming in far enough to provide useful information, but zooming out far enough that readers can see the big picture.

Accuracy and completeness are siren songs #

Authors often have good intentions when making overly complex flowcharts: They want to be both accurate and complete. These are worthy goals in general, but accuracy and completeness can mislead you. You’re making your reader work harder by adding too much detail – even if the detail is accurate and its addition makes the flowchart feel more complete. Worse, readers might even miss the point entirely if the point is lost in too much detail.

The most obvious way to slip into complexity is by adding too many nodes and edges. This is surprisingly easy because your project can appear simple at first glance. This assumption is especially likely for startups because complexity correlates with scale, but that doesn’t mean everything that’s small is simple.

As Marianne Bellotti, author of Kill It with Fire: Manage Aging Computer Systems (and Future Proof Modern Ones), writes “Big systems are often complex, but not all complex systems are big.” She notes a few characteristics of complex systems that any software – new or old; small or large – can have, including: “the number of direct dependencies and the depth of the dependency tree, the number of integrations, the hierarchy of users and ability to delegate, the number of edge cases the system must control for, the amount of input from untrusted sources, the amount of legal variety in that input, and so on, and so forth.”

Even with a relatively simple application, it’s easy to slip into providing too much detail and creating an overly complex flowchart. And even if you’re not overwhelming readers with the sheer number of steps and nodes, you might overwhelm them with the amount of edges.

Take the example below, which doesn’t have many nodes, but does have so many edges that any sense of flow is lost.

Example of a flowchart with a low number of nodes that are complex due to a high number of edges.

A flowchart with a multitude of nodes and edges might be more complete and accurate than a simpler flowchart, but with too much complexity, the purpose of the flowchart will be lost and the reader will be left confused.

Lack of constraints and planning #

Planning your flowchart before you design it can save you a lot of time.

If you dive in, you might realize midway through that you’ve been operating on the wrong level of abstraction and that the final flowchart will be too complex. You might also be adding nodes and edges as you go, only realizing by the end how messy it all looks. Similarly, you can zoom out too far and design a flowchart that makes sense and reads well, but is ultimately so simple that it doesn’t communicate enough meaningful information.

Many diagramming tools actually make this temptation stronger because they provide you with an infinite canvas and an array of shapes and lines that’s likely vaster than you need. Effective design benefits from constraints and a good plan can ensure you stick to the goals of the flowchart.

Maintenance often falls by the wayside #

Maybe you made a perfect flowchart that nails the balance between simplicity and complexity. Good job! But if you don’t have a maintenance plan, then complexity is likely to strike again.

As your application evolves, it makes sense to add new things to the flowchart. It’s harder, however, to return to the flowchart outside of new progress updates and revise it. If no one owns it, people might drop by and add things until the flowchart gets too complex to ignore.

Documentation is already notoriously hard to maintain, but flowcharts are especially difficult because as people add things, a cascade of changes might become necessary. Even one new node or edge can require someone to reshape the whole flowchart.

This is when a tool like Mermaid Chart can be really helpful. Without it, refactoring flowcharts can be daunting, but with it, refactoring can be smooth thanks to version control.

How to keep flowcharts clear and compelling #

Making good flowcharts is easier said than done so to make it more doable, we’ve captured a few best practices that will help you design flowcharts more effectively.

Only illustrate one idea at a time #

In Docs for Developers: An Engineer’s Field Guide to Technical Writing, the authors write that you should “Illustrate only one idea per diagram. For example, show one level of abstraction in a system, one process flow, or a particular piece of logic.” This is a good practice across your documentation, but it’s especially important for flowcharts.

If you only allow yourself to make one flowchart, it’s likely you’ll go wrong. But if you open yourself up to making numerous flowcharts, you can dial in the level of detail to the particular system or process (or subsystem or sub-process) that you’re describing.

You might even dial into different levels of detail depending on where readers are in your documentation. On the opening page, for example, you’ll likely want to be simple and abstract to appeal to all readers, but if someone is digging deeper, you can provide them with a flowchart that zooms further in and reveals further details.

SmartDraw, in a post about effective flowchart design, provides a good example. Below, you can see how one node of a flowchart links to another flowchart that breaks out a sub-process.

Top-level Process

flowchart TB a(Take order) --> b(Charge customer) --> Prepare subgraph Prepare direction TB d{Type} -- Espresso --> bev1[[Make an Espresso]] d{Type} -- Brewed Coffee --> bev2[[Brew coffee]] d{Type} -- Cafè Latte --> bev5[[Make a Cafè Latte]] d{Type} -- Tea --> bev3[[Brew Tea]] d{Type} -- Soda --> bev4[Pour Soda] end Prepare --> Serve[Serve Customer]

Make an Esperesso

flowchart LR clean(Clean Portafilter) --> distribute(Dose and tamp your grounds) --> rinse(Rinse your group head) --> brew(Brew) --> discard(Discard puck)

By breaking up potentially dense or broad flowcharts, you can provide the right amount of detail.

Focus on clarity #

Earlier, we told you that completeness and accuracy can be misleading goals. Instead, we recommend focusing on clarity and sticking to the purpose of the flowchart and the needs of your readers.

Clarity is tough because it requires compromise. Thomas Manshreck, technical writer at Google, writes in Software Engineering At Google that “There are usually three aspects of good documentation: completeness, accuracy, and clarity. You rarely get all three within the same document.” In other words, you have to compromise and especially in the case of flowcharts, it’s best to dial down accuracy and completeness in order to amplify clarity.

The most common way to achieve clarity is to cut down on complexity and this isn’t a bad way to start. Edges are a particularly likely culprit. Try to remove as many edges as possible and only keep those that are strictly necessary. In the example below, we redrew a former example – the one with too many edges – and made the flow clear just by removing some of those edges. The example is fictional, but it illustrates how edges can add complexity.

A flowchart with the same number of nodes but with some redundant edges removed.

That said, simplicity can also be misleading. A seemingly simple flowchart can actually be pretty confusing. Tricia Aanderud, a data engineer and former Senior Director of Data Visualization at Zencos, shows how a lack of clarity can mislead you in a post on code flowcharts.

In the below example, she shows how a seemingly good flowchart – one that maps a SAS program – ended up being almost meaningless.

She writes that a diagram at the following level of abstraction “rarely explained anything other than it took a lot of steps to get where it was going.”

An example of a flowchart ending up being meaningless.

She continues, writing that “The above example really could be any one of 10,000 SAS programs. All it really shows is the actual steps the programmer used, but it doesn’t really help you understand why the dataset was created.”

Instead, she provides an example flowchart where she made sure to “plot the purpose or the logic of the same program.”

An illustration of a flowchart that plots the purspose of the logic in a better way then the previous meaningless flowchart.

As you can see, the second example actually has more nodes, but the end result has greater clarity because it’s focused on what the reader needs.

Similarly, you might be able to add clarity not by removing nodes or edges, but by using better design. In a post about effective flowchart design, Flowmapp provides numerous tips, including using consistent design elements, flowing nodes from left to right, and using the correct shapes for each node.

Less is more, split things up, and use your tools #

Bad flowcharts, whether they’re complex or simplistic, usually come from good intentions: You want to explain everything and make sure nothing is missed.

But if you make flowcharts that are overly complex, you’re making a similar mistake that fantasy authors make when they focus on lore instead of plot. In both cases, the reader is liable to get lost or bored. Similarly, if you make flowcharts that are overly simplistic, you’re creating distraction instead of meaning and you’ll be lucky if readers only skip the flowchart – fluff can make them skip the rest of your documentation, too.

Flowchart design is a game of balance: Dial into the right level of detail, create as many flowcharts as necessary to maintain clarity, and use your tools to achieve a balance that you can maintain over time. Flowcharts are an invaluable tool, which is why they’re essential to so many industries. With a well-designed flowchart, you can transmit a level of understanding that readers wouldn’t be able to get from text alone.