While architecting systems to make the web fast, reliable, and secure, I have always longed for better tools and notation to use to communicate my ideas to partners and colleagues in ways that enable each of us to ask great questions as we explore together.
After thinking hard about this problem and studying lots of related work, I have developed a notation and a technology I call depict that makes it really easy to depict systems inspired by the STAMP framework that I adore.
You can try a demo of the depict technology here for free.
Let’s talk about a system that involves a person and a microwave:
person microwaveThe person can act on the microwave by opening it, closing it, starting it, or stopping it:
person microwave: open close start stopThe microwave can beep to let the person know when it needs attention:
person microwave: open close start stop / beepThe purpose of the microwave is to heat food:
person microwave: open close start stop / beep
microwave food: heatThe microwave contains an important component called a magnetron:
person microwave: open close start stop / beep
microwave food: heat
microwave [ magnetron ]Which actually does the heating:
person microwave: open, start, stop / beep
person food: stir
microwave [ magnetron ]
magnetron food: heatWhen heated, the food becomes warm:
person microwave: open close start stop / beep
microwave food: heat
microwave [ magnetron ]
food warm-food -: becomesIn preparation for stirring and eating:
person microwave: open close start stop / beep
microwave [ magnetron ]
magnetron food: heat
food warm-food -: becomes
person warm-food: stir / eat…and with these few, simple lines, we have just sketched a quite complex visual story about a system involving a person, a microwave, and what can happen between them.
depict is great for taking the most important words you have to describe your system – your nouns and your verbs – and instantly turning them into beautiful pictures.
Some specific uses include:
My favorite use for these pictures is to make designs more accessible by illustrating them.
The typical situation is: as you design pretty much anything, you’re going to be furiously accumulating a growing list of intermediate problems, hypotheses, hopes/worries/fears/anxieties, todos, available side-quests, and so on.
But without a map (or an editor), anyone who didn’t follow you on this journey is going to be hopelessly lost within moments, if they even bother to try to follow your thinking.
Rather than asking your readers to hack through this jumble with you afterward though, you can instead – especially if you are planning to run a meeting to share your results – give your reader a map just by typing up the most important words that you’ve found, and how they relate.
That way, people who didn’t go through the jumble-creation exercise with you — and therefore, who don’t have your personal random-access memories of it — will still be able to make enough sense of the parts of the jumble that remain relevant to ask typical questions about the resulting design.
depict is good at helping communicate “who is doing what?” and “how is responsibility being delegated?” – that is, “divisions of labor”.
By treating boxes as players, nesting as assignment of responsibility, and arrows as authority + feedback, you can get a great (and much more readable) picture of how responsibility is being assigned and subdivided than is reasonable to expect with conventional RASCI or RAA matrices.
Although there is more to do, an important goal of depict is to lower the energy cost required for everyone involved in the design process to participate fully in architectural discussions.
In that regard: how accessible are your current architectural diagrams to users who use assistive technologies like screen readers?
How much does your current diagram editor rely on your colleagues’ abilities to make precise mouse movements like accurate clicking on small targets or to carefully drag-and-drop connectors in order to produce great diagrams?
These are all areas where depict explicity considers accessibility and strives to improve on the status quo.
depict makes it fast and easy to build up a library of system descriptions that you can version-control, copy-and-paste from, and instantly search to create the images you need for whatever story you need to tell or whatever analysis you need to conduct.
Because depict is a based on easily searchable text, you can build up descriptions of large systems from descriptions of smaller parts easily over time.
My 2013 talk: “An Atlas of Systems” sketches a vision and shows a demo of an old implementation of this idea based on a pre-depict system diagramming technology that I was exploring years before I had learned enough to design and build depict.