% 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 ``` microwaveperson? The person can act on the microwave by opening it, closing it, starting it, or stopping it: ``` person microwave: open close start stop ``` microwavepersonopenclosestartstop The microwave can beep to let the person know when it needs attention: ``` person microwave: open close start stop / beep ``` microwavepersonopenclosestartstopbeep The purpose of the microwave is to heat food: ``` person microwave: open close start stop / beep microwave food: heat ``` foodmicrowavepersonheatopenclosestartstopbeep The microwave contains an important component called a magnetron: ``` person microwave: open close start stop / beep microwave food: heat microwave [ magnetron ] ``` foodmagnetronmicrowavepersonheatopenclosestartstopbeep Which actually does the heating: ``` person microwave: open, start, stop / beep person food: stir microwave [ magnetron ] magnetron food: heat ``` foodmagnetronmicrowavepersonheatstiropenstartstopbeep When heated, the food becomes warm: ``` person microwave: open close start stop / beep microwave food: heat microwave [ magnetron ] food warm-food -: becomes ``` foodmagnetronmicrowavepersonwarm-foodbecomesheatopenclosestartstopbeep 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 ``` foodmagnetronmicrowavepersonwarm-foodbecomesheatopenclosestartstopbeepstireat ...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*.