Tracking documentation usually fails in one of two ways. Either nobody writes it, or someone writes a long specification once and it stops matching the site within a few months. Useful documentation is smaller than most templates suggest. It only has to answer the questions people ask when a number looks wrong or a change is coming.
Start from the questions it has to answer
Before choosing a format, list who will read this and why. An analyst sees a sudden drop in a metric. A developer is rebuilding a form. A marketer wants to reuse an event in a new report. Their questions tend to be the same:
- What does this event mean in business terms?
- When exactly does it fire, and when does it deliberately not fire?
- Where does each value come from?
- Who decides if it changes?
- How can I check that it still works?
If your documentation answers these for each important event, it does its job, whatever tool holds it. If it lists only names and tags, it describes the setup without explaining it.
A worked event record
One record per event is enough for most sites. The following example is hypothetical, based on a newsletter form:
- Event:
newsletter_signup - Meaning: a visitor successfully subscribed to the newsletter
- Fires when: the server confirms the subscription
- Does not fire when: the button is clicked but validation fails, or the address is already subscribed
- Parameter:
form_location, text, allowed values and , from the data layer
