New way of marking product feature related code snippet sections

[adinauer]

Problem Statement

We currently use line number ranges to mark areas in code snippets that can be toggled (visible/invisible) based on product features being enabled/disabled.

This is brittle and has caused multiple SDKs to have broken docs already.
It is easy to forget updating the line number range and also easy miss in a code review.

Updating the number range requires copying the snippet into an editor and using that for line numbers. You then also have to guess whether it's 0 or 1 based.

Example:

yaml {filename:application.yml} {"onboardingOptions": {"performance": "7-11"}}
...

Solution Brainstorm

Maybe we can instead use some sort of marker (comment) in code snippets that automatically moves when code snippets are updated.

e.g.

sentry:
  dsn: ___PUBLIC_DSN___

  # Add data like request headers and IP for users,
  # see https://docs.sentry.io/platforms/java/guides/spring-boot/data-management/data-collected/ for more info
  send-default-pii: true

___onboardingOptionsStartMarker: performance___
  # Set traces_sample_rate to 1.0 to capture 100%
  # of transactions for tracing.
  # We recommend adjusting this value in production.
  tracesSampleRate: 1.0
___onboardingOptionsEndMarker: performance___

[a-hariti]

I have a working prototype with this syntax

  // ___product_option_start___ performance
  // some lines here
  // ___product_option_end___ performance

the markers are not rendered,
and solution does not care about the comment syntax difference between languages (as long as it has the ___ sentinel strings)

do you think we should support both syntaxes for the migration or switch to the new syntax and bring everyone to the PR before the merge?

@adinauer @chargome

[adinauer]

do you think we should support both syntaxes for the migration or switch to the new syntax and bring everyone to the PR before the merge?

I don't mind either way, I just think the old way of doing this is very easy to break so we should replace it rather sooner than later. But I guess we can also ask SDK engineers to take a look at their SDK docs and update.