[website_docs] Questions about "Getting started", and OTel website 404s for Java docs

[chalin]

Where's the "Getting started" page?

We're aiming for every language SIG to have a Getting started page. Java used to have one (see open-telemetry/opentelemetry-java#3070), but then open-telemetry/opentelemetry-java#3081 dropped it and another page:

• website_docs/getting_started.md was deleted
• website_docs/automatic_instrumentation.md was deleted

I'm seeing that QUICKSTART.md, now just a placeholder, directs readers to https://opentelemetry.io/docs/java/manual_instrumentation. Might manual_instrumentation be a suitable candidate for a Getting started page? If not, what do you suggest we do to get a Getting started page for OTel Java?

/cc @theletterf -- who is looking into the topic of Getting started pages.

Addressing top OTel website 404s for Java docs

As you can see from open-telemetry/opentelemetry.io#635, the top Java 404s are for the two files mentioned above that were deleted by open-telemetry/opentelemetry-java#3081. When a page is deleted, a redirect target needs to be chosen so that readers who still have a link to the page don't get a 404, page not found error.

So my question here is, what should the redirect target be for the following OTel website paths:

• /docs/java/automatic_instrumentation/?
• /docs/java/getting_started/?
  Note that if we recreate a Getting started page, then we won't need a redirect target.

/cc @austinlparker

[jkwatson]

The docs that were deleted were specially about the Java agent provided by the opentelemetry-java-instrumentation repo, not this one.

If someone wants to write "getting started" docs, or figure out how to use the ones that are already in this repo, that would be great.

[chalin]

Thanks for the context @jkwatson. In the meantime, where should we redirect those two 404s to?

[jkwatson]

Thanks for the context @jkwatson. In the meantime, where should we redirect those two 404s to?

No idea. Probably a good question for the instrumentation folks, since those were their docs.

[chalin]

@jkwatson: can you explicitly cc some of those instrumentation folks here so that they know that the ball is in their court, and also I'll then know who to followup up with? Thanks.

[jkwatson]

@jkwatson: can you explicitly cc some of those instrumentation folks here so that they know that the ball is in their court, and also I'll then know who to followup up with? Thanks.

@trask @anuraaga @iNikem @mateuszrzeszutek

[trask]

@jkwatson or @anuraaga can you transfer this issue to the instrumentation repo (since u have the powers)? thx

[anuraaga]

I've had an idea in mind which this reminded me of. I've been thinking if we should have a separate repo for Java docs and examples for end users (not for agent extension or instrumentation authors). SDK and instrumentation have a lot of related points and I think it's hard to provide a cohesive experience to users by maintaining them in different repos. An example is the gRPC examples in this repo - it should use instrumentation, but it's also awkward for these getting started experiences fragmented. Any thoughts?

[theletterf]

@anuraaga I like that idea, but I wager it's a pattern that'd have to be replicated throughout all language repos. @chalin WDYT?

[chalin]

A separate repo for a cohesive set of examples makes sense, though for the docs for those examples should be a part of the website repo.

[chalin]

In the meantime, I'd like to address the two 404s ASAP, even if the redirects aren't final or optimal.

@trask @anuraaga et al.: until we have replacement pages to publish to the website, would it make sense to redirect both of

• /docs/java/automatic_instrumentation/
• /docs/java/getting_started/

to https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/README.md? (I don't like redirecting away from the website, but this is better than 404s.)

[chalin]

Would it make sense to use https://github.com/open-telemetry/opentelemetry-java/tree/main/examples/autoconfigure as a basis for a Quickstart or Getting-started page?

[chalin]

Just to give weight to my wish to address the 404s ASAP: the top two website 404s in the past week are the two /docs/java pages mentioned here. Thanks.

[jkwatson]

Would it make sense to use https://github.com/open-telemetry/opentelemetry-java/tree/main/examples/autoconfigure as a basis for a Quickstart or Getting-started page?

I don't think that makes sense for either of those things, no.

[anuraaga]

I think for the quick fix we can redirect

/docs/java/getting_started/ -> https://opentelemetry.io/docs/java/manual_instrumentation/

/docs/java/automatic_instrumentation/ -> https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/README.md

[jkwatson]

Moving this to the docs repo.

[trask]

@chalin is there still something that needs to be done for this? thx