[IA] Rename /docs/instrumentation to /docs/languages, and Manual subpages to Instrumentation

[svrnm]

I was once again trying to wrap my head around #3228, and I wanted to start with a first part of what I have proposed in this comment:

• Replace top level section "Instrumentation" with "Language APIs & SDKs". This (imho) makes it also easier for people to find what they are looking for if they are not yet firm in the wording (aka they don't know what "Instrumentation" means)
• Replace "Manual" with "Instrumentation" because this guide is going in detail on how to instrument your code (here I assume that someone went through the getting started and is already aware of what "Instrumentation" is)

This PR purposefully is not yet touching the word "Automatic", this is worth a separate consideration

Final Note, I kick this off as a draft PR for discussion, because right now this PR only changes linkTitles and if we want to go with this change, we need to rename files & URLs and have to manage a ton of aliases.

@open-telemetry/docs-approvers PTAL

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

Redirect tests (selected):

• https://deploy-preview-3761--opentelemetry.netlify.app/docs/instrumentation/
• https://deploy-preview-3761--opentelemetry.netlify.app/docs/instrumentation/go/
• https://deploy-preview-3761--opentelemetry.netlify.app/docs/instrumentation/js/getting-started/nodejs/
• https://deploy-preview-3761--opentelemetry.netlify.app/docs/instrumentation/java/manual/
• https://deploy-preview-3761--opentelemetry.netlify.app/docs/instrumentation/php/manual/

[theletterf]

Sounds reasonable, as it leaves the door open to further variants, such as "automatic instrumentation". I do wonder, though: Isn't this sort of assuming that the code based instrumentation is the default way of instrumenting? That might not be true for runtime languages like Node or Java.

I like @pellared 's structure here, which might inform a deeper restructuring of our docs: #3228 (comment)

[svrnm]

Sounds reasonable, as it leaves the door open to further variants, such as "automatic instrumentation". I do wonder, though: Isn't this sort of assuming that the code based instrumentation is the default way of instrumenting? That might not be true for runtime languages like Node or Java.

I'll make a strong statement now and say, yes, code based instrumentation is the default way, because telemetry should be built-in, so agents and instrumentation libraries are only an intermediate thing until otel is native everywhere. We see this actually happening for Java with the Spring Boot Starter and for Node.Js with nextjs having otel built-in natively (and by that not needing any instrumentation library anymore)

I like @pellared 's structure here, which might inform a deeper restructuring of our docs: #3228 (comment)

I was thinking about this as well, because "Instrumentation" right now also includes "Bootstrap/Setup the SDK" right now, which probably should be extracted (maybe in it's own PR). We have something for "How you "instrument libraries" which is called "Libraries" in some of the languages.

[chalin]

I like this! 👍🏻

[chalin]

As discussed in Slack, add this rule to the new languages index file instead. Follow the Registry page as an example.

[chalin]

Add the following to the Languages index front matter:

aliases: [/docs/instrumentation]
redirects: [{ from: /docs/instrumentation/*, to: ':splat' }]

[svrnm]

thanks!

[cartermp]

I like the concept of the change. I'm happy to proceed with this moving out of a draft for review.

[pellared]

I think it is a great improvement.

[cartermp]

The main thing in my mind here is:

This PR purposefully is not yet touching the word "Automatic", this is worth a separate consideration

It looks a little odd without some tweaks to both the automatic sections and the (if relevant) libraries sections. That's a separate issue to tackle, but it needs tackling.

[svrnm]

The main thing in my mind here is:

This PR purposefully is not yet touching the word "Automatic", this is worth a separate consideration

It looks a little odd without some tweaks to both the automatic sections and the (if relevant) libraries sections. That's a separate issue to tackle, but it needs tackling.

Agreed, we need to review the other section titles as well! Let's have some follow up PRs then

[chalin]

Oops, the redirects for manual pages aren't implemented correctly. Let me see how we can fix this.

[chalin]

@svrnm - actually, if you'd like to merge this now, I can fix the redirects in a followup PR. WDYT?

[svrnm]

@svrnm - actually, if you'd like to merge this now, I can fix the redirects in a followup PR. WDYT?

as discussed via slack I try to fix them right now because there are a few other things that need to be updated (links on the status page)

[chalin]

LGTM. In particular the redirects are fixed.

See inline for minor suggestions.