Add Caution Note re Experimental SemConvs

[mattmccleary]

Following up on Slack Chat:
https://cloud-native.slack.com/archives/C041APFBYQP/p1707760677044609

---

Preview: https://deploy-preview-3995--opentelemetry.netlify.app/docs/languages/

[chalin]

@mattmccleary - FYI, I've added an alert closing tag so that this change will at least build.

[svrnm]

thanks @mattmccleary, this is an important call out. I think we will need to have it at a few other places as well for people to see and recognize it. But we can fix this as a follow up (we can turn your segment into a shortcode and put it at places where we think it is required)

[svrnm]

/fix:format

[github-actions]

You triggered fix:format action run at https://github.com/open-telemetry/opentelemetry.io/actions/runs/7898558642

[chalin]

Wrapping something up, will get back to this PR soon -- I have some extra comments beyond the markdown link reference issue.

[svrnm]

Wrapping something up, will get back to this PR soon -- I have some extra comments beyond the markdown link reference issue.

Sure, then let's not merge this before you follow up!

[chalin]

I've pushed a fix to the alert link-ref issue. The solution is to have the markdown link definition be placed inside the shortcode.

I've also moved the note to be before the table. It makes more sense to me that way.

All that being said, I'd like to suggest that we rework the note prose and/or the opening statement "The current status of the major functional components for OpenTelemetry is as follows", so that it is clear that we're talking about the same/related things.

That is, now I'm wondering what the status table is actually giving the status of. Can we make that clearer?

[mattmccleary]

I've pushed a fix to the alert link-ref issue. The solution is to have the markdown link definition be placed inside the shortcode.

I've also moved the note to be before the table. It makes more sense to me that way.

All that being said, I'd like to suggest that we rework the note prose and/or the opening statement "The current status of the major functional components for OpenTelemetry is as follows", so that it is clear that we're talking about the same/related things.

That is, now I'm wondering what the status table is actually giving the status of. Can we make that clearer?

I agree the table isn't clear, though the title of the page is "Language APIs & SDKs" so I inferred it's a composite of API and SDK. Customers can also click into the languages to learn more. In the future, the table could be reworked to include semantic conventions but that would require some thought because it could quickly blow up the size. Since it's not clear to me how to improve the situation, I'm wondering if this could be a non-blocking follow-on item. I'm happy to think on it some more.

[chalin]

I'd be generally in agreement with what you propose. I might want to tweak the text a bit though -- let me sleep on it :).

[svrnm]

I agree that the table with the status per language needs to be improved, but this should not be a concern for this PR. I'll raise a follow up issue since I also have a few ideas here

[chalin]

PTAL at the reworked note.

[chalin]

👍🏻

[chalin]

Merging. I'll let @svrnm followup with the issue / proposed rework he mentioned.