No one has time to RTM. Let’s reimagine the manual instead
Visualising complex systems
As you may have heard, a decent photo can really help control your copywriting budget. It’s also well known that the London Underground map is much more helpful than any road map, just as long as you stay below street level.
But there comes a time when even sophisticated visualisations fail. How do you explain, say, the earth’s climate? A living cell? The universe? Or even the business rules governing complex processes and decision matrices?
I can at least help with the last one. If you’ve ever desperately trawled an internal Wiki, or hunkered down with coffee, snacks and a complicated flowchart, this post just might be for you.
Why I’m writing this
I’m a software engineer in a business that has many varied network systems, running everything from warehousing to blogging, with workflows as diverse as buying, selling and trading photography and videography kit, and keeping track of inventory.
Like many similar organisations, we have comprehensive documentation for all our systems. But it takes time to read and assimilate. Getting everyone up to speed costs Scrum teams precious time on new projects.
And I could only imagine how complicated it must have seemed to non-technical colleagues — maybe we could cut the costs and stresses of onboarding too? So I volunteered to do something about it.
What follows is a summary of the issue, the systems we considered and the design we’re using to build a usable, useful visualisation of our business processes.
What makes a system complex?
The definition begins at pretty much the point where flowcharts fail.
A complex system is composed of many components which may interact with each other. They’re difficult to model because:
- They’re non-linear — you can’t just follow a simple decision chain
- Some properties may only emerge through the interaction of nodes
- The order of nodes may not be fixed
- The system might adapt itself to changing circumstances
- There are lots of feedback loops.
These commonalities between outwardly different systems has given birth to a distinct multi-discipline research field — start here if you find your interest piqued.
The trouble with text
Sometimes a well-written text can convey information in a way other art forms cannot. As a rule, that time is not during a sprint.
Even user-friendly text can be difficult to wade through.
Metaphors
Even if you know how computers work, the famous desktop metaphor makes a workstation easier to understand, and more efficient, for most of its users. We talk about ‘windows’ as if we were looking inside the machine, and ‘packages’ wrapping up all the ‘files’ needed to make something happen.
But the downside (another metaphor), of course, is that metaphors can become confusing when it comes to painting a complete picture. Speaking of which …
Static visualisations
We’re back where we started, with pictures. You know the sort of thing — pyramids, layers, charts, decision trees.
You may well visualise your system as a network of nodes, but the more complex the system, the less informative such representations become. Map of the world wide web, anyone?
Let’s not think about representing dynamic pages here. Even Minority Report skimmed over that part.
Animating the visuals
Here’s an animation from Google Earth, showing human impact on selected parts of the earth over three decades.
Animations like these help us see ‘through’ the data, straight to the valuable information. They can even represent something of the Z-axis.
I came across some inspiring interactive visualisations during my research. None of them really resembles the approach we decided on, but here are three of the best:
- Interactive map of Reddit — If you want to see what the internet is made of, there are worse places to start than this relational interactive, created from 176m Reddit comments.
- 3D Periodic Table — Start using the filters and the 3D design brings complex data to life. Because you always wanted to see the most abundant elements in the earth’s crust, all at once.
- Nikon Universcale — Powers Of Ten reimagined for today’s universe.
But even for our everyday work reselling photographic equipment, we found plenty of frameworks, designs and other tools that promised to take some of the hard work out of building a visualisation from scratch.
I’ll list some at the end of the article because they may be perfect for your needs. But for now, let’s look at the approach we chose.
Visualising the possible
I won’t bore you with our particular workflows but here’s the general idea.
We’re using XState to create finite-state machines representing our processes and business rules. We then take the output of the state machine and convert it into a format React Flow can consume.
The result is a compellingly simple visual metaphor that’s always available, can be easily updated when the rules change, yet makes sense of complex processes so that anyone can understand them.
This isn’t just about us
Reactions to the prototypes within MPB have been encouragingly positive, to the extent it seems strange that more businesses aren’t doing it. I’m thinking particularly of larger operations where presumably the cost to implement would be highest, but where the benefits are probably highest too.
If an enterprise has a million and one processes, opaque to individuals (particularly new hires), this kind of visualisation could save person-hours aplenty.
And such a system, well-crafted, might even be more than ‘just’ a process model — it’s potentially a management system, a personnel directory, a source of truly relevant messaging …
Earlier I promised to list tools that offer interesting data-visualisation capabilities, so here they are — I’d love to hear what you do with them.
- React Flow — node-based app framework; from simple diagrams to complex interactive editors.
- D3.js — library for manipulating documents based on data, with plenty of examples to examine.
- Cytoscape.js — graph theory (network) library for visualisation and analysis.
- KeyLines — build graph visualisations that turn connected data into insight.
- Graphviz — open-source software to turn text-described structural information into diagrams.
- sigma.js — a JavaScript library aimed at visualising graphs with thousands of nodes and edges.
- vis.js — a dynamic browser-based visualisation library.
Ben Simpson is a Senior Software Engineer at MPB, the UK’s leading reseller of photographic equipment with operations in Britain, Europe and North America. https://www.mpb.com
