17. Build a demo
Thursday, June 22, 2023 / 6 min read

I picked up Ken Kocienda’s book, Creative Selection recently. It’s been a fun and lighthearted read; I like that - in contrast with other books in this space - the author has not explicitly picked several concepts, and attempted to line up and hammer in a row of examples. Instead, the book is a collection of stories.

A recurrent theme was how often new ideas were communicated using a demo. The author used them for new ideas, to move a decision forward, tell when an idea is at a dead-end, or whether it was good enough to be given to users.

A demo and a MVP are not the same. A demo is a piece of code that demonstrates a concept, almost always a user-facing change. It isolates the “aha” part, and makes it real. A demo takes an abstract discussion and shoe-horns it into reality; making it easier to discuss, give feedback, compare with, and iterate on.

A demo is both high bandwidth, and concrete. It conveys a lot of information very quickly (especially helpful when pitching to busy people). It sits in a neat quarter of the MBA-101 matrix; with time to build on the X-axis, and realness on the Y. It takes less time than building it out completely, and a careful engineer can create an almost-production-like experience (close to the top of the realness scale). You can prod it, feel it, frown at it from various angles. When the demo is iterated on, you have a clear A and B to contrast against each other.

To help understand the position that demos sit in, here’s four other options that occupy the matrix.

Just do the change

Attempting to build the change from day 0. It’s high bandwidth and non-abstract. People who look at your work will be able to experience it as a user would in every aspect. Helpful? Yeah. Takes a boat-load of time? Yep. It takes time to figure out the right place to integrate, time to bend your code to support the change. Your idea better be right first time.

Use Figma to demo the flow

Designs in a tool like Figma are a great way to show off how things might look, and how flows through your system might be. This is mid-bandwidth, and non-abstract. It can be done quickly. This is what many teams do, and they do it for good reason.

The downside is that if you have wish to demo something that has a complex interaction, needs specific backing data or logic, or access to tooling not available inside Figma: you’re out of luck.

Write a proposal

Towards the abstract; a proposal doc is low-bandwidth. It takes longer to understand the idea, but it doesn’t take long to produce. This can be a good balance, or a way to get a project kicked off. In many cases, a proposal is still very hard to conceptualize what the result will look like. It’s like when 3 people read a long novel, all 3 will have slightly different pictures of the cast of characters in their head. The conversion between text and image is completely subjective.

10pm Slack message

A Slack message is not the best place to think deeply about your product. This is low-bandwidth, abstract, but takes only seconds. With an aligned team and clearly scoped problem-solution, this can work. However, if you’re building something complex; this will end in wasted time. Learning on the point I made above with writing proposals, this faces the same issue but with less data to help form a coherent picture.

I believe one should look at your terrain as a guide (aka: “it depends”). If you’re climbing a mountain with many hidden turns; a demo could be the boots you’re looking for. Your goal, when demoing, reviewing, and integrating on an interface is to experience it as a user. Get a sense for the speed, how components interact, colors, edge cases; these blend together to help you understand if the concept works. Any product is a series of tiny tradeoffs. A demo is your chance to show the select few you believe are worth making. It tells you whether you’ve solved the problem. It should also give you confidence to spend the time needed to build the production-grade feature.

Building a demo can feel expensive, but what’s the cost of being wrong? By being cognizant of your own uncertainty, you’re going to build a better product. You can’t rush it.

A pattern I sometimes see is when detailed proposal or spec goes out, it receives a few comments. Nothing crazy, you get a semi-committed yes and get to work. Once it’s up and ready for the team to play with, everyone has a long list of (admittedly, helpful) feedback. Wouldn’t demos help here?

After some thinking, I keep circling back to a couple of principles for building demos. The first is to avoid building inside the main codebase. Most of the time, this will make your life harder. If you need packages or data, copy them into your application. I often find that the time spent integrating a feature into an existing codebase takes a long time.

The second principle is to either use the best language suited for the job. To help decide this, I propose:

  1. If there’s only one tool available, use this (i.e. Swift for iOS, TS/JS in the browser)

  2. For small demos: pick up a dynamic language like Ruby or Python. Give yourself a speed-up with Github’s Copilot.

  3. For larger demos: pick the language you’re most familiar with. Don’t use this greenfield-like opportunity to play with something new. Stick with what you know. Your goal here is to get a demo up and to be able to iterate on it quickly. If you’re spending time wrestling the language, it’s going to slow down the flow.

My last point here is about demos and backend engineering. If you’re working on something that never interfaces directly with a human, a demo probably isn’t the right tool. Start with a mock interface, a flow chart, do benchmarks, prove upper limits. A demo is great because people operate better when we see the same thing. Can touch the same thing. If the magic of your work is about achieving better storage compression, or increasing throughput; do you really need people to look at your working demo?

Demos, for the right problems, are powerful. They take time, but it’s paying respect to the fact that people make better decisions when they have something tangible.