
Ask HN: How do you document analytic events? - am1nix
Hi,<p>I&#x27;m a software developer and I&#x27;ve been in different teams where I always found the same problem: how can we document analytic events in a nice way?<p>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&#x2F;Google Analytics&#x2F;whatever
3. There is an event fired when the Sign up button is clicked and it is stored in Mixpanel&#x2F;Google Analytics&#x2F;whatever<p>Problem 1:
Someone (non developer) wants to check how many people clicked on Sign in -&gt; 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)<p>Solution to problem 1:
We create a wiki with a list of all the events and a description on when they are fired<p>Follow up problem:
We need to rename the event OR add&#x2F;remove properties to the event OR trigger the event from a different place OR delete the event -&gt; a developer goes and updates the code -&gt; they forget to update the wiki -&gt; the documentation is now outdated<p>General problem: it is hard to keep up to date documentation on analytic events.<p>I was wondering how do other people handle this?
At the moment we are using Typescript if that info is any useful.<p>Thank you!
======
PaulHoule
I am a big fan of Sphinx

[http://www.sphinx-doc.org/en/master/index.html](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...](http://www.sphinx-
doc.org/en/master/usage/restructuredtext/domains.html)

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
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](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
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
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.

