Ask HN: How do you document analytic events?
I'm a software developer and I've been in different teams where I always found the same problem: how can we document analytic events in a nice way?
Website example: 1. There is a home page with a Sign in button and a Sign up button. 2. There is an event fired when the Sign in button is clicked and it is stored in Mixpanel/Google Analytics/whatever 3. There is an event fired when the Sign up button is clicked and it is stored in Mixpanel/Google Analytics/whatever
Problem 1: Someone (non developer) wants to check how many people clicked on Sign in -> they need to know the event name to be able to check it out (imagine a more complex situation with many events and many interactions)
Solution to problem 1: We create a wiki with a list of all the events and a description on when they are fired
Follow up problem: We need to rename the event OR add/remove properties to the event OR trigger the event from a different place OR delete the event -> a developer goes and updates the code -> they forget to update the wiki -> the documentation is now outdated
General problem: it is hard to keep up to date documentation on analytic events.
I was wondering how do other people handle this? At the moment we are using Typescript if that info is any useful.
Thank you!
http://www.sphinx-doc.org/en/master/index.html
which is sorta like "Javadoc" except you can make custom "domains", out of the box
http://www.sphinx-doc.org/en/master/usage/restructuredtext/d...
for instance you can document C++ or http APIs. It's pretty easy to write your own domains and I wrote an RDF domain that can used to represent just about anything that you can represent in RDF.
It's particularly good when you need to link multiple domains such as an API and its documentation in code, for instance you could document the event definitions in comments in your typescript code and have sphinx cut them out and make user docs for them.
It's an excellent answer to the problems of code and documentation although I have a few complaints such as they made an RST reader without making an RST writer, it uses global variables way too much, etc. But really I don't know anything that attacks the problems that is better.
This is exactly the reason why we built Avo (https://www.avo.app). It's designed for everyone on the team: product managers, analysts, data scientists and developers. It works by generating code derived from an analytics spec, which you create and maintain in a user friendly web app.
You can check it out and reach out to me [email protected], I'm happy to help any way I can.
Since one of the things that was in my properties was an identifier added in build stage for every analytics call in the code if I wanted to figure out what analytics properties came from what lines of code it was relatively easy.
So could track when properties were added, spread of their usage, and using git blame figure out who added it. But we were also a small team so usually I added it.
There were of course various levels of abstraction, but sure I would know when an event happened because a user scrolled by a widget on an external site, on the main domain, when they clicked on the widget, liked it etc. all the normal things you would want to capture if you are measuring widget interactions across sites.
on edit: So in your first scenario - if a non developer wanted to look over all events they might see that there were events named "hotspot seen", "hotspot hovered", "hotspot clicked" and so forth.
In those ones actually there was the widget id that hotspots where in and of course the original interaction id so you could draw a graph of how many users progressed from hotspot seen to product liked and so forth. But at some point a non developer is going to probably have to ask a developer or elasticsearch expert - I need this data out of the system and summed in this way.