Instrumentation guidance for developers

[ljcarot]

Per Adam Case:

Problem Statement

The current CIO documentation for instrumentation lacks clarity and direction, making it difficult for developers to understand how to instrument features correctly. This leads to a low adoption rate of instrumentation, resulting in incomplete or inaccurate data, which hinders product decision-making. By providing a clear and concise guide on instrumentation in context with Carbon components, we can be opinionated on what best practices there are on instrumentation and can empower developers to easily find and instrument features, leading to increased adoption rates and better product telemetry.

Product Outcomes & Instrumentation

Adoption Rate: Measure the number of features instrumented by developers within a set timeframe.
Time to instrument: Measure the time it takes for developers to instrument a feature after being introduced to the guide.

Assumptions

• Developers are the main focus here, and will use the guide to get started with instrumentation rather than the CIO site.
• This may be duplicative work, but I assume that our contributions to this effort will be contributed back to the CIO sites.
• This will live on our Carbon for IBM Products site.
• This should be cross linked with Winning Products and published widely on engineering sites.
• We are basically recreating this site for ourselves
• Use our relationship with Guardium to get this documented.
• Use contacts Hima Chintalapati and Corinne Leopold for technical contacts

Requirements

1. Developers needs to easily find the instrumentation guide so that they can start instrumenting features from the main Carbon for IBM Products site.
2. Developers needs to understand how to get started with instrumentation, focusing on front-end instrumentation requirements first but also consider back-end instrumentation too, and what required properties they need to have in place.
3. Developers needs to understand how to integrate the code snippets into their code (focus on React and Javascript frameworks)
4. In the guide, developers needs to find the instrumentation code snippets easily by component (first starting with "What's new modal components".) (for example, if we use a close out button, what is the corresponding track event snippet that should be included in the onPress event)
5. In the guide, developers and product managers need to know how the instrumentation schema manifests in Amplitude (make it clear how what is shared with Segment looks like in Amplitude)

Note: Approach this as if you were telling someone how to properly instrument their site from a developer experience point of view. This needs to be DEAD simple for a developer to pick up and go. I don't want teams to go: where do you want me to start?.

Bonus: Consider how we could make this repeatable across components so it could be just a prop or simple addition to each component rather than including the event each time.

Resources

I essentially want to approach this like a developer experience for front-end instrumentation (for the first pass). This screenshot is from our own getting started. We do this so well today, let's make it simple for them despite us not owning Segment.

[ljcarot]

I moved it to needs refinement so it can be broken down into smaller tasks on next Refinement call which is Mar. 19.

[elycheea]

Notes from discussion with @jlongshore @ajcase @ljcarot.

Considerations

• Are we assuming teams have already onboarded to Segment? Seems like this has been
• More freedom to include instrumentation details in internal IBM Products site than Core site
• How can we be selective about what teams are actually instrumenting and how teams are making use of the data?

Tasks

• https://github.com/carbon-design-system/carbon-for-products-website/issues/473
• https://github.com/carbon-design-system/carbon-for-products-website/issues/474

---

• Add best practices to the component/pattern page
  • Work with Liz to find a good start/stop event that we might want to start documenting for instrumentation first
  • Is this a separate Instrumentation tab? Or part of the Code tab?

The goal

Developer can instrument patterns/components with minimal setup.