Skip to content

Restructure Analytics Instrumentation Documentation

Goal

Restructure Analytics Instrumentation Documentation to make it simpler, easy to use, flexible for new additions and reduce redundancies between the handbook and docs

Users

  1. Internal Gitlab Team members (PMs/EMs) who are looking to instrument their apps, track metrics, look in the documentation if there are already existing event they could track.
  2. Analytics Instrumentation Team Members (PMs/EMs) who are looking to get an understanding of how things are built at the backend
  3. External Gitlab users

Handbook Vs Docs

  • Handbook will house our vision, direction and development process.
  • Docs will contain
    • All guidance and reference information on instrumenting applications and tracking events/ metrics
    • Architecture and other technical details of the system

Handbook

Docs.gitlab.com

🆕 🚀 Internal Event Tracking

Proposed Path: Docs>Contribute to Gitlab>Feature development>Internal Analytics>Internal Event Tracking

  • Index page with a high level overview and link to child pages ( similar to this page)
  • Introduction -> This should include explanations around the difference between Events and Metrics (similar to the prototype docs) as well as a basic overview of the architecture
  • Quick start -> Instructions on how to create a new Event / Metric using a generator, should include a video
  • Event Definition Guide -> Explanation of all parts of an event definition
  • Metric Definition Guide -> Modify current Metric Definition and link to existing page
  • Architecture -> Detailed architecture and other technical details
  • FAQ's

⛔ Existing Tracking System

Service Ping Content from Docs ❌ Deprecate

  • Separate out pages that need to be deprecated
  • Pages that need to be retained will be left as is
  • Mark as no longer maintained and reference alternate Docs page for pages to be deprecated
  • Remove deprecated pages after a few milestones

Snowplow content from Docs ❌ Deprecate

  • Separate out pages that need to be deprecated
  • Mark as no longer maintained and reference alternate Docs page for pages to be deprecated
  • Remove deprecated pages after a few milestones

🆕 🚀 Analytics Instrumentation Guide for external Gitlab Users (Docs)

Proposed Path: Docs> Use Gitlab > Monitor application performance> Tracking SDKs (related issue)

  • Overview page with index to each lang SDK
  • Each Lang SDK will have its own page

cc @bastirehm @stkerr @lciutacu

Edited by Tanuja Jayarama Raju