DEV Community: Alex Ran

Naming Convention: How to name tracking events

Alex Ran — Tue, 05 Dec 2023 22:16:24 +0000

Read time: 3min

Who is this for

This blog is for individuals and teams, who feel they need a naming system for their tracking events but are not sure what makes a good one.
I will share a ready-to-use naming convention (if you are in a hurry), a guide to find a tailored naming convention for your team (if you have more than 120 seconds), and some tips on how to really solve your problems with a naming convention.

I will not talk about why you need a naming convention in this blog. That deserves its own blog.

The quick one

For a quick solution suitable for most teams, here's how to name your events in platforms like Amplitude, Mixpanel, Pendo, mParticle, Rudderstack, Segment:
page_location.ui_component.action_past_tenseFor example,
web_product_detail_page.add_to_cart_button.clicked

The tailored one

If you want a solution that tailors better for your team, here is how to figure this out yourself in 5-10 min:

Step 1: Figure out the 3 main sections

Page Location: This should be the screen/page of your product.
UI Component: What is the UI the user is interacting with?
Action: What action is the user performing? This can be explicit action like clicked, or implicit action like loaded (the page with their browser)? Choose between past tense and present tense.
Be verbose here; this is where you define the specifics that will save huge time afterward.

Step2: connecting these 3 pieces

Cases:
Using all lowercase is usually safer as some analytics tools auto-convert everything to lowercase. However, you can use camelCase or PascalCase if case sensitivity is not a concern.

Connectors:
Choose from:

underscore '_'
dash '-'
dot '.'
no explicit connector (e.g., camelCase, PascalCase.
'justlowercase' is not recommended as it is hardtoread).
space (as a programmer, I do shy away from this option).

Choose a connector for words within a section: The example above uses underscore “_” to connect words within a section. e.g. “add_to_cart_button”
Choose a connector between sections: The example above uses dot “.”

Step3: put these all down in a simple doc/message, share it out

We have completed the “naming” part of naming convention, now is the time for making it a convention.

Why do I need to do this?
Because it is not a naming convention until most of your team members accept it. Without accepting it, engineers will implement event tracking in malformed shapes, analytics tasks will waste time on questions like “what does this event means?” and “what is that new event called?”

How do I do this?
Honestly, it is not as hard as it sounds:

Put down the naming convention into a 1-page doc, or a short message. Be clear, be easy to understand and to follow. Here is a template:

Tracking events naming convention:
Connect these three section using dot “.”:
page_location: e.g. web_home_page, ios_home_screen
ui_component: e.g. cancel_button, home_menu
action_past_tense: e.g. loaded, clicked, hovered, scrolled
Use underscore “_” to connect words within each section.
For example, web_product_detail_page.add_to_cart_button.clicked
Question? Ping @someone or #some-channel

Stick them to the top of a Slack channel or save this document to an obvious place.
Find some 5-10 minutes in a team meeting to talk about this, get everyone look at it. Address concern if any. Before this discussion, it could be helpful to take some minutes to get supporters (e.g. buy-in from tech lead) in advance if necessary.

Common questions related

Events separated vs. aggregated?
There are multiple buttons located in different places in UI doing similar things, should I name them the same event?

Default to separate events. Aggregate events only when these events are eactly the same, just at different location. Keep a side note or tracking plan for similar events to group them together if needed.
Some downstream tools might not support properties; Saving key information in a property can lead to problems there. It will also be easier to manage when things grow.

Server-side vs. Client-side?
Should I log an event in the frontend or backend?

Intent on frontend client side, action on backend server side.

Originally posted on getseal.co

6 Signs You Need a Tracking Plan on Top of Mixpanel

Alex Ran — Wed, 22 Nov 2023 12:13:41 +0000

read time: 5min

Intro

It is Tuesday morning, 9:45 AM, 15 minutes before the team meeting. You open Mixpanel (or your favorite analytics tool). You are excited to see the results: How are users interacting with the new detail page UI released last week?

First, you want to check how many users (hopefully more) have been using the new UI, but it's hard to find the exact event. After searching, three events—show_detail_page, detail_page_view, and load_detail_page_new—all seem possible. The product specs and Jira aren't very helpful either; they only mention “tracking usage of the new page” without specifying the exact name. You message the engineer who added the tracking and confirm the event is load_detail_page_new. As you think about what "load" means, you see that the number of users has gone up by 50%. This increase is much bigger than what could be explained by the new UI design (even if it is a really good one). You then realize that this was logged differently than you had intended. But it’s now 10 AM, and the meeting is starting. You find yourself thinking about how to deliver this bad news to the team, plan out for a rework and another release.

When there are only a few things to track, these tasks move along okay, facilitated by a combination of Slack messages, Jira comments, a section in each prod spec, and verbal agreements in meetings. However, as the product starts to grow, we often feel tracking issues creep up, consuming more and more of our team’s resources. Sometimes we are moving too fast to realize how much time it has taken until it leads to missed deadlines or poor decisions.

Luckily, this is a problem that can be effectively solved. The solution is a data tracking plan.

What this post is about

I have worked as a data specialist, a software engineer, and a product owner. I have solved similar problems for different teams as different roles. Today I want to share my experience in combating data tracking messes.

In this post, we'll explore six key signs that indicate the need for a tracking plan, and explain how a small effort that can save you a lot of headaches later on.

‘measure twice, cut once'

Signs You Need a Tracking Plan

First things first, do you actually need a tracking plan?

New Team Members Are Lost: When new members join and ask “What events are we tracking?”, or “What event should I look up if I want to analyze this button/flow” it shows a lack of accessible, organized tracking information.
Delayed Product Decisions: If you're waiting to make product decisions because the analytics or A/B test data is missing or seems unreliable, it’s a red flag.
Engineers Seeking Clarifications: If engineers on your team frequently ask about tracking requirements, it means the tracking goals were not planned beforehand.
Misaligned Tracking Implementation: Discovering that the tracking implemented doesn’t match what was initially intended is a clear sign of disorganized tracking processes.
Overloaded Feature Specs: When more than three of your feature specifications or Jira tickets include sections on data tracking, it's a sign your tracking needs deserve a dedicated place.
Data Reporting Doubts: Find yourself wondering if the data is ready to be reported to leadership? This indicates a lack of confidence in your data's readiness and accuracy.

If you've noticed one or more these signs, it's time to consider a tracking plan.

What is a Tracking Plan

A tracking plan is a living document that outlines:

Events: What user interactions you are tracking.
- Naming convention for events
- Using a naming convention is the most cost-effective way to achieve a tracking system that is both easy to maintain and use. There are many philosophical approaches to naming convention. Here at Seal, we use: page_location.ui_name.action, for example, product_detail.add_to_cart.clicked.
- Stay tuned for our next blog, which will talk about event naming conventions in more depth.
Properties: The additional details of these interactions.
Details:
- Descriptions
- Status (Here is the steps we use at Seal, feel free to tune it according to your team’s workflow: 📝 In planning → 🧑‍💻 Ready for dev → 🛠 Implemented → ✅ Ready to use → ⛔️ Update needed → 🗂 Archived)
- Platforms (e.g., web, desktop, iOS, Android, server, etc.)
- UI screenshot (Or, plan directly on Figma designs, see below)
- Other relevant information (like owners, data source, priority, QA notes, etc.)

This document makes sure everyone knows what data is being tracked and how.

Tracking Plan Quickstart

To begin, you can download a simple Google Sheet template here.
If you are comfortable with Figma, this Figma extension allows you to annotate event tracking plan on design files.
You can also book a free 30-minute consulting session with us for more customized help.

How to use a Tracking Plan

Unfortunately, the magic doesn’t happen the moment you download the spreadsheet. It will not solve the problem if your team doesn’t use it.
The good news is, it only takes a little more step: to convey the next steps beyond this spreadsheet with your team:

Assign Clear Next Steps for Each Role: Each team member should know their next step in the tracking process.
The exact task for each role should be depending on your team’s culture. Here is what we do as a reference:
- Plan: Planner(often the PM) will take some minutes to map out what to track in Figma, or in the tracking plan. The status is now 📝 In planning.
- Curation: The team, especially the engineers, spend 10 minutes reviewing and adjusting tracking details. Mark status as 🧑‍💻 Ready for dev.
- Implementation: With detailed requirements in hand, engineers go implement code. Mark status as 🛠 Implemented.
- Validation: After the code shipped to users, a validator(PM, eng, or data) will check the trackers trigger right and data looks right. Mark as ✅ Ready to use.
- Updates: Sometimes things changes, and tracking needs updates. Mark status as ⛔️ Update needed.
Team Reviews: Regularly review the plan as a team to make sure everyone understands and follows it.
- The review usually takes 15-30 minutes. It finds outdated events and tracking debts. We usually do this every month to quarter, depending on how many tracking were changed. ## More Resources about Tracking Plans

Tracking plans vary depending on the project's needs. Here are a few other tracking plans resources:
Amplitude: Create a tracking plan
Segment: What is a tracking plan?
Mixpanel: Create A Tracking Plan
AVO: What is a Tracking Plan?
I also recommend this article: Why most analytics efforts fail

Conclusion

A tracking plan is not just a document; it’s a roadmap for successful, organized data tracking in your product. By noticing this six signs and introducing a tracking plan early, you can save huge for your team by move fast with accurate and reliable data.
Next time a new UI released, you will plan detail from Figma design, adjust tracking plan with engineers, look up this detail in one place, put together a chart, share the result and proceed confidently without any delays.

CTA

I would love to know your thoughts. Please let me know your thoughts and follow for more contents 😎