Finish refactoring Java information architecture

[jack-berg]

Followup on #4966 to finish the ideas in #4853. If / when complete, we can decide if its useful for other languages to follow suit.

• Refactor Instrumentation page into pages discussing how to use the API, guide for library developers, context propagation, using semantic conventions
• Nest Registry, Performance, API (Javadoc) under new "Learn more" section <- Revised strategy in Move performance to java agent, merge javadoc into API page #5590
• Add new Learn the Basics page, introducing users to the otel java ecosystem and routing them to various pages for more information
• Add page describing instrumentation landscape in java and guide to installing instrumentation in applications

[theletterf]

Thanks for following up, @jack-berg !

[tiffany76]

Dropping this here, but I'm happy to create a new issue, if anyone thinks it's necessary.

In the last week or so, we've seen two issues raised by users looking for exporter information in the new Java docs: #5219 and #5255/#12338 .

I know @jack-berg has moved the exporter information into the Manage telemetry page. As we reconfigure the language docs, we might consider highlighting frequently used sections so users can find them more easily.

This highlighting could easily be done on the new "Learn the basics" page that Jack describes above, but I also wanted to point out that the SDK component section seems like reference documentation that doesn't wholly fit with the task-like title of the page (Manage telemetry...). It's also reference documentation that might be useful for experienced OTel Java users as well as new users. So perhaps it makes sense to break the components out into their own page.

[jack-berg]

This highlighting could easily be done on the new "Learn the basics" page that Jack describes above, but I also wanted to point out that the SDK component section seems like reference documentation that doesn't wholly fit with the task-like title of the page (Manage telemetry...). It's also reference documentation that might be useful for experienced OTel Java users as well as new users. So perhaps it makes sense to break the components out into their own page.

I'm not sure I understand this suggestion. If you break out the SDK components section into its own page, what's left on the "Manage Telemetry with SDK" page?

[tiffany76]

If you break out the SDK components section into its own page, what's left on the "Manage Telemetry with SDK" page?

I was thinking it could be a much shorter landing page, with child page(s) for the components. I think the main issue is that people looking for information on exporters and other components don't realize those docs are part of the "Manage telemetry" page. If the nav were to include headings for the components (as child pages) it might make them easier to find. But I'm not attached to any particular fix. I just wanted to raise the issue.

[jack-berg]

I think broadly speaking, we have two emerging classes of pages:

1. Technical reference pages. These are things like the current Manage Telemetry with SDK, Configure the SDK, and the "Record Telemetry with API", "Instrumentation" pages from my proposed Refactor java instrumentation #5276. These pages are a collection facts. They're fairly comprehensive, but are long and so can be intimidating to find information on.
2. User workflow pages. These address a specific user workflow: I want to export to zipkin. I want to add manual instrumentation to my app. I want to to install the otel java agent. These pages address concrete user needs, but because they're so targeted, the information architecture starts to collapse when you try to scale them. We end up with pages like the current instrumentation, an amalgamation with little / no organizing principles serving a bunch of purposes all at a substandard level.

In my mind, the answer is to be clear on when a page is a technical reference page, and when its addressing a user workflow. If we cleanly separate the two, the user workflow pages become much more concise, since they can focus on the task at hand and link out to appropriate technical reference pages to expound on the details. The technical reference pages are like an encyclopedia, and not very many people read an encyclopedia front to back - they use indexes to find the information they need.

When I look at the collection of content that represent the user workflow pages, I see a bunch of content which is better served as content in the examples repository. To use a few of the examples I gave earlier:

• "I want to export to zipkin" has an example
• "I want to add manual instrumentation to my app" has several examples, but the http example is probably most relevant
• "I want to install the otel java agent" has an example

Here's my proposal:

• Let's keep going on the path I've started to introduce technical reference pages. We need a place to state facts and we don't want the facts to be polluted with a bunch of one-off user workflows.
• Let's add a new section in the navigation hierarchy collecting all the user workflow pages we want to target.
• For each user workflow page, include snippets based on a corresponding example from opentelemetry-java-examples (users love code that actually compiles and runs), and let's link out to the technical reference pages whenever applicable.

[tiffany76]

In my mind, the answer is to be clear on when a page is a technical reference page, and when its addressing a user workflow. If we cleanly separate the two, the user workflow pages become much more concise, since they can focus on the task at hand and link out to appropriate technical reference pages to expound on the details.

100% agree. And I also agree to keep going forward with the proposed work. Coming at the issue of reference pages from a technical writer's perspective, the page titles we've selected (Manage... Configure...) are not typical headings for reference topics. They are worded more like titles used for user workflow pages: they start with a verb and indicate the action or task to accomplish. As we fine-tune, rethinking the page titles might help with cleanly separating the two types of topics, and making content easier for users to find.

[jack-berg]

As we fine-tune, rethinking the page titles might help with cleanly separating the two types of topics, and making content easier for users to find.

I'm happy to work with you all and iterate. My priority has been establishing quality technical reference pages because they are the foundation. In some sense the current titles are correct. "Manage Telemetry with SDK" <- this is an exhaustive guide to managing the telemetry with the SDK. Now, most users don't probably want to sit down and read the whole thing, and so we're tempted to write an abridged version. But some users will need the snippets of information that would be omitted, and shortening the content doesn't make the title more correct. 🤷

[svrnm]

Full ACK on the technical reference pages vs user workflow, that's also why I proposed that we introduce a new "Learning OpenTelemetry" path on the website here based on suggestions by @avillela, @jpkrohling, @hughesjj and others. I already played around with an implementation example, so I can share that soon, but to begin with feel free to take a look into https://docs.google.com/document/d/10HD5cdmKWza6GdS4Jdea3T74kqfXaVaaOwZ1juzFk5s/edit