Create a "Get starting with PI guide"
Problem
During the customer interviews I've conducted with internal dev and product managers, I've learned that most team members who seek documentation about instrumenting metrics at GitLab are dissatisfied with our current documentation.
Some specific problems cited include:
- There are too many resources, it's overwhelming.
- I don't know where to start.
- I have no idea which tool will fit my need.
- I get to a certain point and then don't know what to do next.
Proposal
Let's create a step-by-step type of guide for our internal customers (GitLab devs, PMs and data analysts). The guide to be a separate subpage which is linked to from the existing Product Intelligence Guide.
Content
This will be a starting point for a developer or PM to land when they have the need to instrument a new metric/event. The actual documentation/instructional content shouldn't live on this page, but we should provide links to this information on this page. The step-by-step guide should start at determining which tool is the right one for the use case and end at building a Sisense chart with the newly created data.
Step | Objective | Notes |
---|---|---|
Choosing the right tool. | User should be able to understand what tools are available, view use cases applicable to each tool as examples and have a firm understanding of the pros and cons associated with using each tool. | We have some of this in the existing guide but I've received feedback that it is not very helpful. |
Event/metric instrumentation. | Ideally, the instrumentation documentation is provided in a step-by-step manner, but we do not need to refactor the existing reference docs during this issue. | This should be segmented by Snowplow vs. Service Ping. We should include reference to standard context and available helpers. |
How to validate your code. | We should include reference to naming conventions, explanation of category options, required information, and anything we're validating for during review (so the user can anticipate this up front) | |
When to create a data team issue. | There are some cases (like the creation of a new xMAU metric) when a data team issue is needed. Link to this reference. | Example issue: https://gitlab.com/gitlab-data/analytics/-/issues/11662 |
When to create a Product Data Analysts issue. | There are some cases (like the creation of a new xMAU metric) when a data team issue is needed. Link to this reference. | |
How to verify your data. | Now that the code has shipped, explain how the user can find the data - how will they know what table to find it in? | |
Build a dashboard. | The user should be able to build a basic dashboard in Sisense with these instructions. | We can link to data team or Product Data Analysts handbook reference here. |
Supplemental Reference Links
- From the landing page we should link to other relevant documentation and tools which will be needed in the instrumentation journey. Examples:
- dbt data tool
- Sisense handbook page
- Metrics dictionary
- Tutorial section - a catalog of links to YouTube videos we've recorded as specific guides
- FAQs