% Introducing *depict*, a tool and notation for depicting systems
% Michael Stone
% September 10, 2022
# Introduction
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.
# *depict*
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](https://mit.edu/psas) framework that I adore.
You can try [a demo of the *depict* technology](https://mstone.info/depict/)
here for free.
# *depict* Examples
Let's talk about a system that involves a person and a microwave:
```
person microwave
```
The person can act on the microwave by opening it, closing it, starting it, or
stopping it:
```
person microwave: open close start stop
```
The microwave can beep to let the person know when it needs attention:
```
person microwave: open close start stop / beep
```
The purpose of the microwave is to heat food:
```
person microwave: open close start stop / beep
microwave food: heat
```
The 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: heat
```
When heated, the food becomes warm:
```
person microwave: open close start stop / beep
microwave food: heat
microwave [ magnetron ]
food warm-food -: becomes
```
In 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.
# What is *depict* good for?
*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:
## Illustrate designs
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.
## Communicate roles
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.
## Make architecture more accessible
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.
## Build a library of parts
*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.
## Build an atlas of systems
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"*](https://mstone.info/posts/talk-atlas-20130327/) 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*.