Ask HN: How do you document analytic events?

[am1nix]

Hi,

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!

[PaulHoule]

I am a big fan of Sphinx

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.

[am1nix → PaulHoule]

Interesting! I will check it out, thank you.

[arnihermann]

This problem can be so detrimental for teams who want to measure the success of their products it's hard to put into words (ಥ﹏ಥ)

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 a@avo.sh, I'm happy to help any way I can.

[bryanrasmussen]

If you build your own analytics system which I did when I needed one, data was stored in elasticsearch as analytics events, then I had a query that told me every property that was used.

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.

[am1nix → bryanrasmussen]

Is not a bad idea for building the event list, but it doesn't solve the problem of documenting when or by what the event is triggered, something that a product owner or a data scientist that don't know the code might want to know to do some analysis (Sorry, I forgot to mention it needed to be for non developers)

[bryanrasmussen → am1nix]

well that is what the normal analytics functionality of the system was, basically on meaningful events you would make a call to analytics function and pass it an object with the properties you wanted to analyze, it would add some global properties and send it off.

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.