Use Code Names With Your Project or Suffer the Consequences

I have a story about failures in communication to tell so that others might learn from it.

I have worked with a programming team long enough already to learn where many of the major breakdowns can happen during development. The biggest hurdle to overcome on any project is how to facilitate proper communication. I could write a whole book on why clear and concise communication is important to the success of a project but today I'm going to focus on naming conventions. At first glance naming conventions don't seem like a big deal and many teams do not really give them much thought. Microsoft is probably the biggest offender when it comes to naming conventions; they will call something by its internal technical name and then they let that terminology leak out into the world so that everyone is nice and confused when they hear it. For example, their new tablet-centric operating system is not Windows 8, it's Windows RT. They called it that because Windows RT only contains the newer WinRT API and completely removes the old Win32 API while other versions of Windows 8 for desktops will include both APIs. This was a terrible idea that is now confusing both developers and consumers.

A similar problem happened at my job recently and it is a shining example of why naming conventions are extremely important. I won't go into great detail about the project itself but the surface requirements were to create a new way to view a report. Rather than downloading a PDF of a report to their computer, the user would instead get to view the report online in an interactive way. I took some extra time, outside my working hours and outside my commitments, to talk with him and get on the same page together so we could build something great. The idea was progressing smoothly and I was excited to tell my team about it. I was worried that my team wasn't going to share the vision that marketing and I seemed to share but they liked the idea just fine. What they didn't like was the name.

Because this report was being brought online it was no longer a simple scroll from top to bottom report. It was now an interactive section of the site where they could browse a report as if it were a miniature website. As such, marketing named the project "report microsite". Literally a microsite would be a subset of related web pages strung together via hyperlinks and related information. Technically this microsite was more of a report viewer application because no actual web pages are involved; in fact the entire viewer is just a custom jQuery plugin our team would write. Despite the differences between the literal definition of the term microsite and the technical functionality of the project I didn't have an issue with the name. Probably because I was too excited about the project to care. I felt like marketing and IT were about to embark on their first successful project with minimal friction. The history between our two departments was wrought with conflict, but the new head of marketing seemed quite willing to work with us.

Well as you can probably guess, my team detested the name. They hated the term so much that they refused to call it that. If I said "microsite" when discussing the project I would immediately be caught in a hail storm of debate about something I considered to be extremely stupid and undeserving of any discussion. Had I been the team leader I would have told everyone to suck it up and just call it what the domain expert wants to call it. Unfortunately the actual team leader was the one most perturbed by the name. I didn't want to bring such a silly debate back to marketing, but I thought if they were more willing to bend than my team then the conflict could be resolved quickly and we could get back to discussing things that mattered. Oh boy how wrong I was.

I barely mentioned calling it a report viewer to the head of marketing and a holy war was born. He refused to budge and so did my team. If I used the wrong term in front of the wrong people the conversation would instantly devolve into a smattering of useless argument and criticism. Hopefully you see what has happened here; an environment was instantly created where I now cannot even speak about the project I am working on. I would constantly talk around the project, trying not to call it anything and instead only talk about the specifics within the project. Inevitably I would say the wrong thing and then I'd be saddled with spending the next 30 minutes trying to steer the discussion back to important issues.

Luckily, up until yesterday I never had to deal with both parties in the same room together. If I was careful I could call it "report viewer" in the IT department and "microsite" in the marketing department and nobody would be any wiser. Of course as I'm sure you can tell, this was a bomb just waiting to go off. We had a meeting yesterday with my team and the domain experts for the projects we were working on. One of those domain experts was the head of marketing. When the proverbial talking stick landed on marketing during the meeting, he brought up a simple feature he'd like to add to the microsite. I had a question about this new feature because I didn't quite understand it. I proceeded to verbally trip over myself and land on the detonator that was wired to the pile of dynamite beneath the floor.

"Where should this new feature be located? Should it be inside the micro--- uhhh, report view--, the project?" I stammered, revealing the controversy that I had been able to mostly squelch up to this point. Of course nobody heard my actual question about where to place this new feature. The only thing the ten people in the room heard was me stutter over what to call the project. The head of marketing immediately piped up "You mean microsite right?". Then the team lead chimed in to explain why the name doesn't work and why we should just call it the report viewer. I literally face-palmed at this point and just sat in my chair listening while the battle ensued. The tension in the air was palpable and I was seriously seconds from leaving the room. My disgust with the situation was obvious, but I managed to maintain my composure just enough to speak up and say that it wasn't the appropriate time or place for the discussion. Everyone stopped at that point, but tensions have been high since.

Afterward I came up with the idea to use project code names like bigger software companies do so that there is no confusion about what to call a project during development. I put together a somewhat detailed proposal and emailed it to marketing and my team. During the meeting I was disgusted that this stupid debate was even taking place, but both sides took my disgust as disagreement with their position. So when the head of marketing received my proposal it was pretty obvious that he read it defensively. I maintained an extremely neutral tone in my proposal and was trying to appeal to both sides. That blew up in my face. Nobody on my team liked the idea because it was still different from what they wanted to call it and the head of marketing didn't like it for the same reason. Basically we are now stuck at a "my way or the highway" mentality on both sides and it's all about probably the most stupid thing it could be about.

So now I am caught in the middle of development hell and there is no end in sight. My team still wants to argue about how stupid the name "microsite" is. The head of marketing replied to my email with an authoritarian tone, talking to me like I'm an idiot and telling me if I want to discuss further then I should escalate it to my manager; he even did it in a reply to all so that everyone got to see his disapproval of not only my idea, but also of the way in which I conveyed it. Suddenly the project I was so excited about has become a project I barely want to think about, let alone work on.

So what's the lesson here folks? Come up with an agreed upon project name before you begin any form of work. If there is even the tiniest inkling that there will be confusion about the name during development then use a code name that has no literal definition related to the project in any way. Let the domain expert figure out how to brand it after development is over if they must, but have your naming conventions in order before you begin. Trust me, it will save you massive headaches.

UPDATE:

I have since left the company where this mayhem ensued. It was the best career decision I ever made. I now have a high paying job with a high profile employer that actually knows how to produce software without arguing about silly trivial things like what internal name to call something.