How to get the most out of your Product Analytics with Naming Conventions
clean👏 data👏 starts with👏 naming conventions!
Let's put it plainly. When it comes to data collection, dealing with inconsistent, confusing data labels is time-consuming and super annoying.
The data mess builds up gradually as developers use different words to describe the same user interaction: “Login”, “Log in”, “Logged In”, and “Successfully Logged In”. Messy, inconsistent data is data debt that should be dealt with as seriously as technical debt.
Without a consistent naming convention in data collection, your team will be confused about which event correctly corresponds to a user activity like logging into your app. To guarantee consistent, clean and easy data analysis, your product analytics strategy must have a naming convention framework.
What is a naming convention? 🗺️
A naming convention is a set of rules for labelling data. Naming conventions help to clearly identify and categorise an “event” in your product or service. Usually, this is a PDF document, spreadsheet, or section in your technical documentation website. The naming convention document should describe the framework for filling in the event schema and creating data labels.
Alongside every naming convention, it's essential to include plenty of examples and document any edge cases or “quirks” in your naming convention to provide an easy/clear understanding of the use cases. Your team should refer to this set of rules to quickly create a data label for a new event, resulting in data being labelled consistently and clearly.
How to start naming conventions 🛠️
If you don't know what you should track on your product or feel your data is already too messy - you need a tracking plan first. After you start the tracking plan, you'll likely find the patterns or rules that will become naming conventions.
Just like journalling can bring clarity to your ideas, creating a tracking plan will clarify what events to track and what naming conventions suit your product.
Creating a Tracking Plan: 📝
Setup: Use a spreadsheet, Miro board, paper or whiteboard. Step 1: At the top of your workspace, describe a typical user journey performed by your user on your product. For example, a user signing up for your product or making a purchase.
Step 2: Break up the user journey into steps that the user he user takes to start and complete the whole user journey. These steps will turn into event data!
For each step/event, answer the following questions:
Event context - What happened in this step?
Define the actor - Who made this happen? Did the user perform this step? Did the system/code automatically perform a step?
Document the details - What was created or updated? What are the important details about this step?
If you have an event schema, start converting these questions into the schema.
In this article, I will use the Mini Digital core schema for these examples.
You can get a copy of this Tracking Plan template by following this link.
Object + Action Framework 🏄♀️
I recommend using the object+action framework because it's easy to visualise what object your user is interacting with and what action has taken place. This framework is widely adopted by product analytics tools, including Mini Digital, as a fundamental convention for event names.
The object+action framework is simple. As per Mini Digital Docs, firstly choose your object - this is the object (a noun) that the user is interacting with or the system/service is interacting with:
A button
A screen or page
A data entity like “account”, “wallet”, “blog”, “image”, or “product”
Then, choose the action verb to describe how the user/system interacted with the object. In the object-action framework, the verb is in the past tense:
created
clicked
selected
viewed
connected
Now, putting it all together, object+action, your event reads as walletCreated
or walletConnected
and defines your eventName
property.
To keep your event data consistent and predictable, it's best to reuse the words chosen for objects and actions across your events.
Bad event names 🙈
When it comes to data labels, the simpler the label, the better. You want to use language that does not change often, and that is also easy to understand for new team members. Here's a list you can include in your naming convention to define what should be avoided in the data labels:
Case - choOse 0ne plz. 👻
Choose one case and stick with it. In your naming convention, specify what case the data labels should be written in. To keep your tracking code tidy, consider adopting the case already used in your codebase.
The casing is important for making sure you are consistently tracing the same user interaction. For example, Wallet Connected
and wallet_connected
will be considered two different events even if they are actually the same user interaction.
snake_case —
wallet_connected
camelCase —
walletConnected
All lowercase —
wallet connected
Proper Case —
Wallet Connected
Sentence case —
Wallet connected
Acronyms 🛸
Avoid using abbreviations formed from the initial letters of other words in your data. Not everyone in your team or business may accurately recognise what each acronym means. Another disadvantage is that acronyms tend to change over time, which means your tracking will need to be updated any time this happens. You might have to consider relabelling historical data to keep everything the same. That's a lot of effort, and why I recommend avoiding acronyms.
Instead of abbreviating the words, consider using the complete words/names in your event name or creating an additional event property where the full acronym is the data label.
❌ event_name: HITS_link_clicked
✅ {event_name: link_clicked, additionalProperties: {hyperlink_topic_searched: Health}}
The only circumstance I consider allowing an acronym in the data label is if the acronym is common knowledge and widely used in the world. For example, NFT is an acronym for Non-Fungible-Token, and it is widely found in articles, documentation and online conversations. It's unlikely to change, so it may be an exception in my team's naming conventions.
🆗 event_name: NFT_created
Names and personally identifying information 💁♀️
Avoid using project, team, personal names, or personally identifying information in your data labels. Your data labels should be generic rather than specific to a single user, team, or project. Instead of including these personal details in the event name or data label, they should be added to the event properties. As event properties, these personal labels can be used in filters to identify a specific user, team or project.
While team names and project names might not be personal information, these names tend to change often over time, which means your tracking code will need to be updated, and you might have to consider relabelling historical data to keep everything the same.
❌ event_name: team_avengers_dashboard_viewed
✅ {event_name: dashboard_viewed, additionalProperties: {mini_digital_team_name: avengers}}
❌ event_name: sarah_jane_account_created
✅ {event_name: dashboard_viewed, additionalProperties: {account_name: “Sarah Jane”}}
Numbers, codes, dates and IDs 📆
Avoid including numbers, codes and IDs in your data labels, as this numeric information is only useful with reference to another resource. Instead, create event properties inside the event to document this numeric information with a data label that provides context to refer to.
❌ event_name: payment_16_Aug_2023_viewed
✅ {event_name: payment_viewed, additionalProperties: {payment_paid_at: 2023-08-15T01:03:52+00:00}}
❌ event_name: payment_231ab90z_viewed
✅ {event_name: payment_viewed, additionalProperties: {payment_id: 231ab90z}}
Mini Digital tip: Mini Digital core schema has entityType and entityId properties that are designed to document the object/entity the user is interacting with, so the payment_viewed
event I used as an example above could also look like this without additional properties:
✅ {event_name: payment_viewed, entityType: payment, entityId: 231ab90z }
Multiple-languages 🌏
Using multiple languages in data collection could result in having multiple events for the same user interaction, so choosing only one language in your naming convention can help keep your data consistent and tidy.
If your team and customer base are multi-lingual, consider writing clear rules and exceptions in your naming conventions on when to use a specific language.
Prefixing and Suffixing 🎏
When I name events, I think about the “state” or “timing” of what the user is doing in the user journey. While I'm supportive of using meaningful prefixes and suffixes to capture this “state”, avoid using less specific words like “new”, “old”, or “final”. These words are subjective and can be interpreted differently by different people. For example, the event name product_viewed_final
is not clear or concise. The word "final" is often used to indicate the completion of an event. However, this can be misleading, as the user journey can be ongoing or have multiple stages. It is better to use more neutral terms, such as "initiated" or "completed".
Remember that the entire event schema should provide context for the event. Don't rush to add all the details in the event name. Rather, keep it simple and create more event properties for each detail.
❌ event_name: final_payment_viewed
✅ {event_name: payment_viewed, additionalProperties: {is_latest_version: true}}
I would definitely avoid adding the “state” of the codebase, product or project. While you might suffix your files with “my-photo-finalFINAL.png”, don't put that kind of stuff in your event data.
❌ event_name: new_version_payment_viewed
✅ {event_name: payment_viewed, additionalProperties: {payment_version: 3.0.2}}
I use “first” and “last” prefixes and suffixes when it's in the context of the object, like a page in a list.
❌ event_name: first_page_viewed
✅ {event_name: payment_viewed, additionalProperties: {payment_number: 9, is_last_page: true}}
I avoid using these words to describe the user's first or last experiences with the product. To find the first time a user did something, like viewed a payment, I just find the earliest created instance of that event in my data set. In the example below, I add an additional event property new_to_user
, to document the first-time experience. This way, I filter all payment_viewed events
to see exactly which one is marked to be the user's first experience.
❌ event_name: first_time_payment_viewed
✅ {event_name: payment_viewed, additionalProperties: {new_to_user: true}}
Here's my suggestion of some alternative words to prefixes and suffixes:
new -> initiated, created, added, started
old -> existing, previously_seen, visited_before
first -> first_time, initial, unseen
last -> final, completed, ended
final -> completed, resolved, closed
Our data is already messy! What should we do? 🫣
It's going to be okay! My advice would be to create or update a tracking plan of all the events being tracked on your product. Audit your code base and your database to find all the events being tracked. This is a great opportunity to review and add new event tracking to guarantee that you're fully tracking user journeys.
I recommend doing an audit of your data collection at least once every 6-months. Use a tracking plan to do the data audit, check each data label against your naming conventions and enjoy the benefits of having consistent and effective product tracking.
Once everything is in a tracking plan, check your existing events and data labels against the naming conventions. Then, it's time to iteratively make updates to the code based on the tracking plan.
You could also consider updating historical data to align with naming conventions. Do this carefully - make sure not to delete or override the database.
Closing up 🙌
It takes time to get your data clean and consistent, but it is even more time-taxing to work with messy data all the time.
Here are my top 3 points to achieve clean and consistent event data for product analytics:
Use object+action for event names
Use additional event properties to document details. It will keep your event name simple
Use a tracking plan to play around with words and identify inconsistencies
Want a tracking plan for your team? Book an online Product Analytics Workshop where I will take your team through mapping user journeys, identifying key metrics and coming out of the workshop with a tracking plan. These workshops are perfect for teams that haven't started product tracking and those who want to clean up existing tracking. Get in touch by clicking the Learn More button on the Mini Digital website.