Tracking Plan

Records used to get planted wherever a feature happened to be built. An engineer named a button, pointed it at the analytics tool, and that was the whole process.

The bill arrived about six months later. Mia asked how many document shares had happened last month, Theo opened the analytics tool, and three similar event names were sitting there: doc_shared from the web app, shareDocument from the mobile app, and Document Shared from the browser extension. Nobody could say whether the three should be added together.

A second problem turned up in the same session. The share event carried no attributes at all, so there was no way to separate a copied link from an email invitation. The count of 3,200 shares was available, but which method people preferred would take new instrumentation and another month of waiting.

A tracking plan moves that agreement earlier. What gets recorded, under which name, with what carried alongside it — all decided in one table before feature work starts, and engineers instrument from the table. It pairs with the naming convention, which standardizes how names are formed: the convention is the rule, and the plan is the list built under that rule.

One row is one event. Seven columns cover the basics.

1. Event name. The literal string, spelled as the convention requires. If the name in the document and the name in the code differ by one character, the document has stopped being useful.
2. A one-line description of what it counts, written as a condition. For sharing, this is where you fix whether it fires when the share button is pressed or when the other person actually receives the invitation.
3. Where it fires. Which screen the behavior lives on. If the same behavior exists in three places, all three get listed, which is what stops the name from splitting.
4. Where it's sent from. A column marking whether the event goes from the user's device or through server-side tracking. Anything involving money or permissions belongs on the server.
5. Attributes. The event properties carried on the same line. For each one: the name, the value's shape, the allowed values, and whether it's required. For share method, the allowed values might be link, email, and workspace, and nothing else.
6. The question this record answers. Which metric or which open question it exists to serve.
7. Status and owner. Whether it's proposed, in progress, or verified, who owns it, and when it shipped.

Values that attach to a person rather than an action get their own table instead of mixing into the event rows. Plan and company size are user properties, and they belong there.

Column 6 is the one most often left blank, and events with that column blank become the burden first. Nobody queries an event with no stated use, but the code still carries it, so every change to the feature has to account for it.

The first draft comes from the product manager who owns the feature, because column 6 only gets filled in by someone who knows what question is being asked. Where a dedicated data person exists, they review whether names and attributes match existing rules; at fifteen people, the product manager usually does that review too.

There are three readers.

1. Engineers, at the moment of instrumenting. They copy the table as written. Nothing outside the table gets planted, and when something needs adding, the table changes first.
2. Analysts, six months later, checking what a given name actually counts. The one-line description in column 2 earns its keep here.
3. New hires, using it as the first document for finding out what data already exists.

The time to write it is before feature work begins, alongside the spec. Fill it in after the build and the exercise becomes copying already-planted names into a document, which leaves column 6 permanently empty.

Maintenance is part of writing it. When a feature changes, the meaning of its events changes, and editing the meaning under the same name mixes old records with new ones inside one name. Move the share event from button press to invitation delivered and the count drops about 30 percent from that day forward; with nothing written down, someone reports next month that sharing is down. So when a meaning changes, the event ships under a new name and the old name stays with a deprecation flag.

"There's no tracking plan for this feature yet. Please fill it in before development starts."

Instrumenting has to live inside the same schedule as the feature itself.

"There's an event in production that isn't in the plan. Do you know who added it?"

The document and the code have drifted apart, and one of the two has to be brought into line.

"Don't change what this event means — ship it under a new name. Six months of values would get mixed together."

Swapping a definition puts old and new data under one name and breaks any comparison across the boundary.

At Pagedeck the table lives at the bottom of the spec document. Mia writes the screens and behavior for a new feature and then fills in the event table at the end of the same file, and Theo reviews just that table before starting work. The column that draws disagreement is usually number 4. When a plan upgrade comes up and someone asks whether the client can send it, the answer lands on the server, and because that decision stays in the table, the discussion doesn't repeat on the next feature.

The most common misreading is that this is an engineering document. The output ends up in code, so the impression is reasonable. But the substance of the document is deciding what you want to know, and that's product work. Hand the writing to engineers and the names come out shaped around what's convenient to implement — page views instrumented densely, screen by screen, while the behavior anyone actually wanted to see goes missing. Records like that can't fill a dashboard, and six months later the needed events get planted from scratch with another month of waiting.

The second frequent belief is that it's written once and then done. Tidy it up early and everything after feels like reference. But features change, their events change with them, and a plan left un-updated is worse than no plan. With no document you go read the code; with a stale one you trust it and publish the wrong analysis.