Sometimes when I talk about customer use cases for software that I’m building, it confuses the people I work with. What does that have to do with engineering? Is my product manager out on leave and I’m standing in?

I’ve found that customer stories connect engineers to the problems we’re solving. When we’re designing a system, we ask ourselves “what if” questions all the time. We need to explore the bounds of the solutions we’re creating, understanding the edge cases. We consider the performance characteristics, scalability requirements and all sorts of other important technical details. Through all this we imagine how the system will interact. It is easier when the software has a human interface, when it interacts with regular people. It is harder, but just as important, when we write software that only interacts with other software systems.

Sometimes the software that we are building can seem quite unrelated from the human world, but it isn’t at all. We then need to understand the bigger system we’re building. At some point, the software has a real-world impact, and we need to understand that, or we can miss creating the positive effects we intend.

On many teams over many years, I’ve had the opportunity to work with other engineers who get this. When it works there’s a rhythm to it, a heartbeat that I stop hearing consciously because it is always there. We talk to customers early and often. We learn about their problems, the other technologies they use, and what is the stuff they understand that we don’t. We start describing our ideas for solutions in their own words. This is not marketing. This influences what we invent. Understanding how to communicate about the thing we’re building changes what we build. We imagine this code we will write, that calls some other code, which causes other software to do a thing, and through all of the systems and layers there is some macro effect, which is important and time critical. Our software may have the capability of doing a thousand things, but we choose the scenarios for performance testing, we decide what is most normal, most routine, and that thing needs to be tied directly to those real effects.

Sometimes we refer to “domain knowledge” if our customers have special expertise, and we need to know that stuff, at least a little bit, so we can relate to our customers (and it’s usually pretty fun to explore someone else’s world a bit). However, the most important thing our customers know, that we need to discover, is what will solve their problems. They don’t know it in their minds — what they describe that they think will solve their problems often doesn’t actually. They know it when they feel it, when they somehow interact with our software and it gives them agency and amplifies their effect in the world.

Our software works when it empowers people to solve their problems and create impact. We can measure that. We can watch that happen. For those of us who have experienced that as software engineers, there’s no going back. We can’t write software any other way.

Customer stories, first hand knowledge from the people whose problems I’m solving spark my imagination, but I’m careful to use those stories with context from quantitative data. I love the product managers who tell me about rapidly expanding markets and how they relate to the use cases embedded in those stories, and research teams who validate whether the story I heard the other day is common across our customers or an edge case. We build software on a set of assumptions. Those assumptions need to be based on reality, and we need to validate early and often whether the thing we’re making is actually going to have a positive effect on reality.

Customer stories are like oxygen to a development team that works like this. Research and design teams who work closely with product managers are like water. When other engineers can’t explain the customer use cases for their software, when they argue about what the solution should be based only on the technical requirements, sometimes I can’t breathe. Then I find the people who are like me, who work like this, and I can hear a heartbeat, I can breathe again, and if feels like this thing we are making just might be awesome.

I built a fake fireplace in celebration of our team shipping Cloud Functions for Firebase. The codename was “hearth” — the product was almost ready for public beta by the time I joined the team, yet I know it was an epic journey to create a long-awaited feature and I felt the milestone deserved dramatic punctuation.

Red brick surrounds a monitor with video of log fire, wooden top has rows of whiskey bottles and a card

If you would like to build your very own fake fireplace, here’s how…

Initial Research

I reached out to our helpful facilities staff to make sure that I understood the constraints of the space. (I didn’t want to buy or create something that would be immediately taken down!) James Miller from facilities investigated some options:

“Since a hearth is technically the flat stone floor or the part outside of the fireplace, putting up just a fireplace and mantel leaves out the most important part, but including it presents a tripping hazard.” He suggested a quick and easy solution would be to temporarily change the display play a 8hr yule log video or on extra computer monitor with some fake foam bricks. He noted that some prop fireplaces which look pretty good in the photos, but are just cardboard. There are more expensive electronic fireplaces, but we can’t have anything that includes heating features similar to a space heater, and he reported “most that I’ve seen online are also missing the most important part… the actual hearth.”

Initially I felt that a literal interpretation of the “hearth” code name was not a critical element. We explored buying a real fake fireplace, but the ones we found were very small and we felt they were very expensive relative to the potential impact. However, his thoughts on the meaning of “hearth” later led to some important design elements. I love being involved in a collaborative creative process!

James suggested that something in a stage prop style would have dramatic effect, perhaps using styrofoam so that it would be light and easy to move, if we needed to shift it in the future around team moves. In brainstorming location, he helped me remember to pick out a spot with an electrical outlet.

Measure Twice, Cut Once

an aisle with people at desks on either side, at the end is a small bookshelf with bottles of alcohol and above that a large monitor on the wallI surreptitiously took a photo of the area, and arrived early one morning with a tape measure to determine its maximum dimension.I then measured the computer monitor I planned to use to determine the minimum internal dimension.

There was actually a third, very important measurement: the internal size of my car, which later became a critical optimization. I designed the fireplace in three pieces, so it could fit into the car, which also made it much lighter and easier to transport. Styrofoam is rather fragile, and the smaller pieces fit easily through doors.

Tools & Supplies

Tools: tape measure, hammer, screw driver, propane torch, safety googles, mask, electric drill, electric sander, garden shears, mat knife, level, steel square

Supplies: small nails, wood, styrofoam panels, gorilla glue, sandpaper, acrylic paint (red, yellow, white, black), gloss latex paint (off-white), sharpie, cardboard

I had never worked with styrofoam before and read that it could be carved with a sharp knife, acetone or a hot knife. If it were a small project, a regular soldering iron would likely have been fine, but I wanted something that would be fast and really liked that the propane torch I found had two different tips as well as an open flame option. The small hand-held propane filled torch is also easier to work with than my electric soldering iron which requires an extension cord.

Construction Details

I tested carving and painting the styrofoam very early, including figuring out how long the paint took to dry. I found that painting the white cracks before painting the red bricks made it come out a bit better. It was also good to test carving to create an effect that looks like mortar.

See key steps in photos

  1. Wooden frame: I uses 1″ thick boards for the frame. Discount Builders in San Francisco has a friendly staff and cut long 12′ or 8′ boards into the lengths I needed. The hearth is a separate component, which is like a hollow box with one side missing, where the missing side is actually attached to the larger frame, so the top can rest on it for stability and is not actually physically attached. I used a level and steel square for an even frame and wood screws.
  2. Top: I used a single 1″ thick board and drilled small holes for pegs to attach the top to the frame in a way that could be easily removed, yet fit snugly. I used garden shears to cut a long wooden dowel into 1″ lengths to create the pegs. I used an electric sander for rounded edges on three sides, and finished with fine sandpaper. I then coated with a few coats of gloss paint (which would have been easier if I had remembered primer!).
  3. Styrofoam: for the large panels I found that using small nails to hold the styrofoam in place made it easier to keep everything steady while gluing it all together. I attached all of the styrofoam panels before carving bricks with the torch. Large cuts were most effective with a mat knife.
  4. Carving the bricks: I found a few inspirational Fireplace images via Google Image Search and drew bricks with a Sharpie, then traced the lines with the torch using the soldering gun tip. Then I went back and made the brick edges a bit irregular and created a few cracks in random bricks. I also used an open flame in areas to create more texture.
  5. Painting the bricks: I mixed acrylic paint with a little dish soap and water, which makes it easier to coat the styrofoam. I noticed that most fireplaces have irregular brick colors, so I varied the colors a bit with yellow and brown highlights, as well as black “sooty” areas.
  6. The inside is painted black with a piece of cardboard as backing.

Additional Resources

I studied sculpture in college, so I had practical experience with wood construction, and learned a bit more from the amazing people who publish about their experience on the web. Here are some links to resources that I found particularly helpful.

Tutorials

Videos

Someone recently observed that I was motivated by a big vision and that some engineers are not, and that’s ok. In my experience, it’s not okay. I wish it was. It’s fun to sink into the code and get into the zone and not worry about the complicated real world. However, it’s not fun to work hard and create something over months or years and have it fail in the marketplace or, worse, never ship at all. I’m not talking about research projects where the primary outcome is learning something or publishing a paper. I’m talking about the kind of software I work on, which is intended to be used by other humans, whether they be developers or regular folks.

There are a few common problems I’ve seen happen when a team writes software without a clear and focused vision.

  1. Lots of bugs are discovered late. When engineers are focused on their own specific component or library, it often happens that another engineer will use that library in a slightly different way than was intended. This is especially true for internal libraries where there is little need for documentation since we can see each other’s source code; however, we don’t typically review all off the code our systems depend on. So each part of the code does what it is supposed to do on its own, but when we put them all together, slight miscommunications add up to things not working quite right, typically discovered late in the development cycle.
  2. The system doesn’t work well. When you are building software as a team, engineers work on different parts of the software. If one engineer is making a gaming engine, and another engineer is making presentation software, it rarely comes together to work well at the end. The gaming engine needs a high framerate and quick response to user input. The marketing presentation software need to display text at large font sizes. It’s likely one or the other will suffer, or more typically the software won’t actually work well for either use case.
  3. You delivered the features your manager asked for, but the product isn’t successful. Customers aren’t happy… or they aren’t buying in the first place. New users and people already using your product have different needs and slightly different use cases. It can be a delicate balance to walk. When developing a “feature” it can be easy to miss a step in between what you are working on and something that seems unrelated from the inside, but which people need to use together or in sequence. I call these features in between the features, which are very hard for engineers to see if they don’t have a complete picture of how people will use the product.
  4. Customers are happy and the product is cancelled. Companies have internal metrics by which they evaluate success. Someone on the business side has determined if we expect immediate revenue, or if this is going to be a long bet and expect slow revenue growth while we focus on strategic customer adoption, or if we need a large base of free users before we expect significant revenue. Sometimes it’s a product that supports larger business goals and drives adoption of a different product. If the engineers don’t know what those goals are, they may not get the important details right to make those goals happen.

So, you need to tell engineers the internal metrics, but that’s not enough. No one writes code that by itself increases 28-day active users. Somewhere in the product plans (or the minds of the executives) is a hypothesis that there are some new or improved use cases that will cause people to use the app more (or to sign up in the first place). A lot of teams do document use cases or user journeys and share them with the engineers, which is important, but not sufficient.

Engineers need to know the use cases that everyone believes will be required to make the product successful; however, usually software engineers have to make all sorts of decisions outside of the required use cases for the next release. The software will work better if all of these little decisions are aligned somehow, and the easiest way to do this (in fact the only way that I’ve found to do this), is for the developers to have a shared vision of what this software wants to be — not just in its next release, but in the future. This vision can be somewhat arbitrary for it to work (which means it is totally fine if it changes), the key point is that it needs to be shared, and when it changes, the change and reasons for the change need to be communicated effectively. A shared vision not only aligns all of the little decisions that developers make independently, but also makes all of the design discussions more efficient. We can focus on how we are building a thing, because we already know what we are building and why.

To create a shared vision, we need to answer: who is the target customer? what are the key problems we are solving? what will our customers be able to do with the initial release and what do we hope they will be able to do in the future? Who are the customers who might not be satisfied with our product and that would be ok?

Good engineers will build something that works for a wider audience. Often the software will enable those people to do many more things than the minimum requirements, but focus is key to creating robust software that works well.

I’ve been talking about engineers, since that’s my focus these days and because there remains a persistent myth that engineers don’t need to be distracted with all this business stuff. All of these questions and answers are even more important for designers, technical writers, support, developer relations, support, sales, business development and everyone involved in the making of and communication about the product.

I’m not motivated by a big vision. I’m motivated by impact — not potential impact, real impact. I need to believe that my day to day work is going to add up to something that solves real problems for real people in the real world. I’ve discovered that to reduce risk in software projects, every member of my team must be able to see a through-line from their day-to-day work to shipping software that causes a large number of humans to be empowered to do something new or better, enabling them to solve real-world problems. To do that, I need to convey a vision that lets the individual team members innovate, coming up with creative solutions in their domain that add up to a system that actually works.