What's in a Name: Naming Conventions and Their Place in Analytics
Morning coffee in hand, you fire up your analytics tool. Whoa. 27 more events got created last night? That’s awesome!
About six months ago you finally convinced your team to start using analytics. Now data will be the loudest voice in the room in driving decisions. After three months of teaching people how to use the tool, referencing it in meetings, and holding people to data-based KPIs, your team’s starting to get the hang of it.
Now they’re even defining events on their own! That is exciting. Let’s see what got added:
Uh-oh.
It’s great to see all those events! But … um, events 1, 4, and 6 appear to be the same thing. Likewise, events 2, 3, and 6. In fact, they could all be the same event. And wait, who is Bob?
This isn’t how events are supposed to be named. Sigh. You’ve walked the team through this before. Everyone has seen your doc — you know, the one in which you outline (in great detail!) the plan. It includes all the events that need to be tracked, where in the codebase those events are located, and exactly how to name each event.
Great. You’re not fixing Bob’s mess, so you message him. You’re nice, so it’s all can-you-please and a reasonable by-the-end-of-the-week…until you realize he’s no longer with the company.
Guess you’ll just have to do it yourself. Instead of working on strategy, interviewing new candidates, planning your next sprint, you’re caught up in fixing events.
Onboarding a new analytics tool is all hunky-dory until the above starts happening. Documentation and video tutorials on best practices in naming your objects only go so far. The sheer number of events, combined with how easy it is to duplicate each existing event, can quickly spiral out of control — at Heap, we call this entropy.
Entropy creeps up on you like a level three hoarder situation — you’re not sure which events to keep, so you keep them all. Slowly you (and everyone else in your org) begin to have trouble finding the event you’re looking for. And even if you do eventually find it, how can you be sure it’s tracking the thing you want it to track? And can it even be trusted?
How bad governance happens to good people
Ensuring good data governance practices isn’t the first thing on people’s minds when they’re running analyses. Yet how many of us have experienced the sinking feeling when we’ve realized we’ve let things get out of control? You know you’ve entered the realm of entropy when it becomes difficult, even painful, to continue using your analytics tool for its intended purpose.
Naming conventions are one of the first defenses against entropy. Unfortunately, a simple standard naming practice is too often dismissed as unimportant or lost in the scramble of last-minute analyses. Before you know it, you’ve snowballed into entropy.
There are a number of ways in which not defining a naming standard can lead to entropy:
Users of the same account end up creating duplicates not realizing the same events already exist.
Events become prefixed with “new” or “use this!” in order to guide other account users on which events they should be using in their analyses, which can get confusing in the long run.
While an externally enforced document is a first step in the right direction, it is yet another document that needs to be updated and maintained.
Organizational turnover means best practices on account maintenance often leave with the person who helped create them.
From interviewing customers, we had two key takeaways about how they use/would like to use Heap to better govern their data:
Data admins of more mature Heap accounts take a couple of hours each month to make sure events are up to date, that data is flowing in, unused events are deprecated and newly created events are appropriately named. This is something they would much rather not spend time on.
Heap admins prefer other regular users of Heap from their organization to follow an established naming convention without exception, and so resort to creating an external document detailing appropriate usage of the tool, and hoping everyone respects and follows it exactly. However, socializing this document is another effort in and of itself, and there are chances some users end up missing it altogether.
So we thought, what if we took it a step further and baked taxonomy into the product? Here’s what we came up with:
Introducing naming conventions in Heap
Today, Admins or Architects in Heap can enable the naming convention feature by navigating to Account > Manage > Data Governance.
Once there, you’ll be prompted to configure the prefixes, which are the building blocks of your event names. The default prefixes — “Location” followed by “Action” — is one way to ensure you cover both breadth and depth of your product surface as you start defining events.
For example, for Location, we may define website (our marketing site), app (in-app pages), and help center (our documentation hub):
And on each of these pages, you might want to ensure the range of actions — view, click, submit and change — are being captured:
That’s it — the setup is done.
Now, whenever someone from your team clicks “New Definition” to define something, they’re going to see some guardrails like so:
All they have to do is give a descriptive name for the object they’re defining, and voilà!
How exactly is this going to help?
Spark joy
It eliminates the possibility of duplicates being created in a way that would make Marie Kondo proud. Next time someone tries to define the “Sign Up” button on your website, they’re likely going to go through the same definition flow and realize that an identical event already exists.
Better discoverability
The primary thing you’re trying to achieve with analytics event naming conventions is discoverability and understandability, at scale. Naming conventions improve the overall “glanceability” of a dataset — and this becomes especially important once you start building reports with these events. You will be able to see at a shot, all the areas of your product that have already been defined, opening up the possibilities for more analysis.
Save time
Unless this is your firstborn, you really shouldn’t have to think this hard about a name. This is a means to a better end, not the end in and of itself — so let us help you keep it simple and functional.
That said, baked-in naming convention isn’t a solution to the overall challenges that entropy poses, but it is a first step to tackling current and future entropy issues your organization might face.
This feature is far from perfect! We hope you’ll give this a shot and send your feedback to us at design@heap.io.