If there is one lesson I wish the tech industry could learn about itself, it’s that most people wish we would talk less and listen more. Because the state of tech diagramming is bad. It has lost sight of the listener, and the story it delivers is TMI: too much information. The result of TMI for the listener is usually a sense of awkward discomfort, and ultimately, boredom.
Here is a typical chart of a cloud architecture:
Another systems overview chart from the United States Military:
When things are busy at Postlight, I probably end up drawing one layercake a day. If you work with me, you’ve seen my layercakes. At its simplest, a layercake is just a diagram made of a stack of boxes, and the basic idea is that the boxes on top are “powered by” or “built atop” the boxes below. Here’s a classic layercake — the “Semantic Web” layercake from 2002 — where each technology builds atop the other or connects to the others:
At its peak, a layercake is a storytelling aid that could fit on a playing card. It communicates the technological solution to the audience, and it becomes a tool they can use to tell a story of digital change to their peers, or maybe to their boss. Stories precede solutions. When we present the layercake, and someone asks, “Can you send me that diagram?” — that means it did its job.
Overbuild, then carve away
When communicating about technology via a layercake, you should remember that all software is basically the same. You might exclaim, turning away from your standing desk and throwing your Nintendo Powerglove to the ground:
“The hell it is, Sirrah! I use functional reactive programming to create user interfaces that are dynamically coupled to graph-based schemas! And that’s hardly anything like creating user experiences that are loosely coupled to relational data stores!”
Okay, and I love you. But listen: Don’t start there. Start here:
- Some software manages data
- Some software manages user experience
- Some software helps the data software talk to the user software
If that just seems embarassingly, awfully basic to you, well, that’s right. That’s where most people are. Would you rather be right or would you rather build software? (Think before answering.)
Since we’re in agreement, let’s draw all software ever as a diagram.
Pretty good, right?
Let’s say someone scheduled a call because they’re working for a government health agency. They tell me:
- They want to make it easier to book appointments for medical screening using smartphones
- They need to message people reminding them to comply with their medications and schedule follow-ups
- They expect hundreds of thousands of appointments and interactions per month
- They want to use off-the-shelf software, but their constituents use old smartphones, are SMS-first, speak many languages, and in some cases have cognitive or physical disabilities
First, I listen to them for an hour. I love this part. You learn about whole industries, ways of seeing the world, and you hear unbelievable horror stories about bureaucracy and exploitative consulting firms. What people get out of watching all the Marvel movies, I get out of listening to stories about global consulting firms. Big consulting is my Thanos.
After the call, I draw the three boxes above. Then I start to expand and move things around until I have a rough sense of the platform. It usually looks like this after an hour or so:
That’s for you to see the process. I would never, ever present this. Sometimes I keep going until I can’t think any more thoughts. Then I schedule a follow-up call. And a few hours before the follow-up call, I sit down and take away absolutely everything I can.
Share the plan, not your work
As a writer, it’s hard not to show all my work and notes and list out every sub-system. As a technologist, that’s even harder. But people are not buying documents. They are buying relationships. When you try to prove you heard someone by showing your work, you often stop listening. It’s more important to keep listening.
“So I took what we discussed last week,” I say, “and sketched out how I think it could work. I’d like to work through where I am and understand your requirements a little bit more.”
Now I bring up this plan on a shared screen in the video call (or hand it out on paper when we’re in the same room, inshallah) and talk through each layer and each box, asking questions as I go and noting the responses.
Yes, as an occasional systems architect with taxonomist tendencies, I know the diagram above is kind of infuriating. It doesn’t actually tell you what’s inside the systems. It doesn’t mention CRM. Where is HIPAA? Different things are much more work than other things. No arrows connect anything. What is read-only and what is read-write? What cloud will it be hosted on? You can’t just say “third-party integrations” and leave it at that.
I am here to tell you that you can, and should.
If that conversation goes well — and often it does — we will be asked to prepare a proposal. Now our layercake gets eaten. It is turned into a table of contents and becomes the outline of our scope of work. All of the questions above should be addressed and turned into a plan, a budget, and a schedule. It is time to drill in, list all the integrations, and show off just how much you can do.
Making good layercakes
For most of my layercakes, I use a tool called Whimsical. Other tools that work fine include any presentation software, plain HTML with tables, or a piece of paper. I like Whimsical because it gives me almost no control over anything. For example, if I want to use color, I choose colors in the order presented in the palette dialogue. I avoid letting boxes have multiple sizes. When it comes time to make things nice, a designer should help me. Pride is the enemy of a layercake.
A good layercake:
- Invites scribbling
- Lets you see a whole system in a few blinks
- Leaves room for interpretation
- Works like the table of contents of a book
- Shows data/back-office at the bottom and user experience on the top
Frankly, I am embarrassed to find myself writing at such length about something so unbelievably simple. But then again, I am embarrassed to be in an industry that thinks spackling 500 clip-art illustrations into a document until it looks like the wall of an Egyptian tomb is good communication.
So, make it simpler. Then make it simpler yet. Make it so simple you’re ashamed to say it out loud.
Now say it. Believe me, people will be happy to hear it.