Named Things

Naming things is hard, but simply leaving it at that elides a lot of detail that I think is very instructive. I've been trying to write this post for a while, but I couldn't figure out how to frame it. So, I think what I'll do is just tell the story that inspired it. I'll be changing some names and details, because I'm not trying to call anyone out. This is a cautionary tale, nothing more. It's the story of an internal tool development project. We'll call it Astro.

A few years ago, I was working at a large company. In fact, this story begins not too long after I started there. My onboarding as a developer had been difficult and lengthy, which meant it was unremarkable in that environment. Just one of the things people learn to accept as normal over time, even though it doesn't have to be. But it was still raw for me. When I heard about a project starting up to work on some new developer tooling, I was hyped. That is exactly my jam. Then a couple of other things happened right around the same time. First, I had a surgery coming up, so I was going to be out on leave for a bit to recover. Second, my manager's portfolio of projects got shuffled around in a minor re-org. Generally, contractors stayed with their projects and permanent employees stayed with their managers, so I no longer had a project. Obviously, I would be assigned a new one, but with my surgery coming up, everyone agreed it didn't make any sense to spend all that time redoing onboarding to another app only to then immediately go out on leave. The result is that I had no obligations for about 2 weeks, and I got to spend most of that time assisting with the Astro project.

Countdown

A little bit of context is in order. First, all of this happened under the umbrella of the retail web organization. This was the set of teams responsible for the user facing web apps at the company, of which there were many. We owned just about everything that happened in the browser, and—most of the time—one layer of REST services to manage interacting with back-end resources which we did not control. And second, Astro was pitched as a replacement for the application template that most of our existing apps were built from. That template was hard to use, practically impossible to update, and several years old. It itself had been a replacement for an even older template. Why all the templates? Honestly, I don't know. That was the pattern, and it was a battle I chose not to fight. The important thing is that the Astro template was a familiar concept, and it seemed to present an easy path for new apps to get onto a more or less current version of Angular. This was an Angular shop. There was a lot of "modernization" going on, so there was also no shortage of new apps because all of the old ones were being rebuilt. Probably not a course I would have set, but again, that was not a battle I had any interest in.

It's also important to explain what I mean by "template". When I call Astro a template, that might give the impression that it did some kind of templating or customization. It did not. It was really just a snapshot of a hello world application that was configured to run in the various environments that retail web maintained for development and testing. It also ran locally on developer machines, which was an improvement over the previous template. The "apps" that were being modernized were actually pages of a monolithic ASP.Net application, and new apps still had to rely on that monolith, which was the main source of everyone's onboarding struggles. So, eliminating that as a development dependency in most cases was very welcome. This created a different set of onboarding work, of course. That was documented, but the docs were scattered and hard to find. If this sounds like I'm being harsh, I don't mean to be. This was a genuine improvement. There were also a couple bits of dev infrastructure built as part of this effort, and those were also helpful. However, that infrastructure was essentially invisible to most people. So, what people saw and interacted with was the app template.

Launch

So, I assisted the Astro team for a little while, to help however I could. I remember being told that it was mostly built, which caught me off guard because as far as I knew they had essentially just started. But, okay. What they wanted from me was a CLI app to kickstart new projects. Think along the lines of the angular CLI, or the Vue CLI, or create-react-app. They wanted me to just build that. Which is fine, that's something I can do. Not at that level of completeness and on that timeline, but I can get something done. They had already selected a framework for building that command line interface. Not the one I was familiar with, but again, fine. I was just there temporarily, they're the ones who would have to support it, so it's not unreasonable to dictate that kind of thing. I tried to explore what they wanted out of this CLI, but they weren't receptive. This team was 3 developers and no one else. Requirements gathering was not a, uh, top of mind concern for them. So, I did my best.

Over the next 7 or 8 business days, I built this CLI app. That part itself was trivial, since it didn't do much of anything. I built an init command to copy their template files and I built plumbing for an update command, along with a few other small things. Where those updates would come from was an open question. The CLI was distributed by cloning the repo and building it yourself. Which, coincidentally, was exactly how the template was distributed. But I was building a tool. That simply wasn't a viable way to package or distribute a tool. So, after the couple of hours it took to build that skeleton CLI, I spent the rest of my time trying to make it distributable. I vendorized the template files, so they could be managed as a dependency of the CLI app. Then I templatized the template files themselves, at least a little. I wanted to run them through a templating engine and produce closer-to-final results. It wasn't a lot, but my goal was to have that templatization in place so it could be expanded later. I broke out some of the template files into isolated components, so that the CLI app could continue to be useful over a project's lifetime. For example, by bootstrapping new models, controllers, services, tests, or potentially other things. Again, not a lot, but enough to establish the pattern and build upon it over time. I rebuilt the template using those componentized parts. I built tests for all of that. Then I wrote some docs, and some notes on my thought process and vision for the future. At that point I was out of time. I sent them a completed PR of the whole effort. The couple of intermediate PRs I'd sent had been ignored. And then I logged out and went to go have a major surgery.

Back to Earth

After my recovery, I came back and joined a new team working on new apps. Or, at least new to me. When I checked in on Astro, I learned that they had just thrown away the work I did on the CLI. Apparently, it wasn't what they wanted. I'm not sure if they ever connected that with refusing to engage when I tried to ask what they wanted in the first place. At this point, again, it might sound like I'm being harsh. I'm not trying to be. This is just what happened. I was irritated, so I dropped it. I did maintenance work on my new-to-me app and tried to get to know my new team for a couple months. Until it was our turn to get modernized.

The Astro team had continued pitching their work around. They did a lot of very slick looking demos that lasted 15 minutes, and they had the support of the right people. They wanted to put it into practice. My new team wound up being the 2nd or 3rd app to get built on Astro. So I looked into what had become of it in the last several months. They built their CLI, which was little more than a shell script to clone and then detach the template repo. There were some predictable hiccups in the initial onboarding and set up. But, once we cleared those challenges, it was great. For a little while. Shortly after we discovered there were problems running these apps through CICD. We discovered the bundled design system components were from the wrong generation of the design system. We discovered that not everyone had access to one or more of the various git repositories where these things came from. We discovered lots of problems like this. And to be fair, that's to be expected. You don't know what you don't know, so you do the best you can and deal with problems as they arise.

The problem was that they hadn't built any mechanism to enable responding to those unknown problems. In fact, they hadn't built very much of anything at all. Frustratingly for me, they had even rejected work I did that would have provided a lot of that mechanism. There was one proof of concept hello world app that they called a template, and a utility to download it for you. So every issue, every bug, every change in the environment had to be handled individually by the teams building these Astro apps. Some of these were problems with what little Astro actually did provide. Some weren't. None of it was catastrophic, so more teams and apps were moved onto Astro. Those development teams grew annoyed with the disappointing reality they found. They expected things to be easy, to just work, to provide solutions. They expected this because that's what they'd been told to expect. Astro organized office hours and a knowledge sharing chat. They wrote a contributing guide, although I don't know if anyone took advantage. It didn't seem to change anything. People continued to run into problems that felt like they should have already been solved, and would assign responsibility to the Astro team.

The Lesson

The point of this story wasn't to complain. It's context for what I'm trying to talk about. See, the Astro team didn't create an app, or a product, or a service, or a tool. They made some starts on some of those things, but none of it was substantial enough to amount to much. What they had created was a brand. Astro was a name that was disconnected from any discrete or tangible thing. At some level, the Astro team knew this. During the couple of weeks I was working with them directly, the Astro team invited me to a working session that was pitched as a kind of mini-hackathon. I was expecting to spend the day doing problem discovery then prototyping solutions. That was not the experience. They spent hours trying to figure out a versioning scheme. Not a guide or process or method of versioning something. A naming scheme for their versions of Astro. As though they would be Android releases. Should they be named after NASA astronauts? No, there's really only a couple astronauts people recognize. NASA mission programs? No, it turns out there's really only like 3 named programs. And so on. After a while, I suggested constellations. I wasn't trying to encourage them, I was trying to end the topic and move on. At the time I thought they had gotten themselves into a bike shed, and I was trying to help get it built so we could work on something substantial. But nothing of substance ever came. Not in that meeting, or in the project generally. I think that's why they rejected the work I had done on the CLI app, too. It didn't fit into their mental model of what they were doing. The constellation idea did stick eventually, so that turns out to have been my one actual contribution.

The point is that names have power; they matter. Names are signifiers. That is, they connote significance. Names also suggest purpose, or membership, or identity, or independence. They carry a lot of weight and implied meaning. This is part of why it can be hard to name things: because names are important and sometimes there's just some intrinsic difficulty in doing it well. When that team created the Astro name, people inferred things that weren't there. When they continued to promote Astro that reinforced people's assumptions. It's not that Astro was a bad name. In fact, for a brand, Astro might even be a great name. The issue is that people thought they were getting a solution, not a brand. There was simply no "there" there, but creating and promoting the Astro name anchored a lot of attention onto this empty space. The problem is that Astro should not have been named  at all.

The other reason naming things can be hard is that the model isn't useful. It's hard to name things because you're naming the wrong things. The things you're naming are not actually anything. Not their own thing, or not real. They're artifacts of your mental model that aren't a useful representation of your problem space. The difficulty of naming things can serve as a warning. Think of it as a design smell. Sometimes things are hard to name because they only exist in the model, and the model isn't serving you. Take it as a prompt to reevaluate how you're thinking about the problem.

Cover photo by Edvin Richardson