Group java performance, javadoc, examples, registry under Learn More

[jack-berg]

Resolves #5211.

Reduces the prominence of the Java Performance, Javadoc, Examples, and Registry by collecting them under a "Learn More" section. This reduces the number of entries under the Java section by 3, focusing user attention on the pages which are more likely to be useful and hopefully making the navigation less overwhelming.

[cartermp]

Approved content and moving around, pending approval from others on the infra changes

[jack-berg]

Realized that without this, there's no java entry in the "Language APIs & SDKs -> API References" section. Moving the javadoc to be nested under "Learn more" means that we need to add a special case to this shortcode like dotnet.

On a separate note, while I've linked to the javadoc page for consistency with the other languages that have an external link, it would be more useful to link to the Record Telemetry with API page, since that includes explanations, examples, and javadoc links for all the key API surface area.

What we link to is a question of whether we value consistency or usefulness more.

[svrnm]

the purpose of this list is to make the API references (read: JavaDoc) accessible more easily. So while I get your point that people should read the api components page first, this is more for people that have read that page and need quick access to JavaDocs (or the equivalent in another language)

I think this is the only thing that bothers me with this change, that we break that consistent like /docs/languages/<language>/api to point to the available documentation

I wonder if we could have a canonical URL outside the structure, like /api/<language>

cc @chalin

[jack-berg]

I think this is the only thing that bothers me with this change, that we break that consistent like /docs/languages//api to point to the available documentation

To be fair, dot net already breaks that uniformity. I understand your point though.

[svrnm]

I think this is the only thing that bothers me with this change, that we break that consistent like /docs/languages//api to point to the available documentation

To be fair, dot net already breaks that uniformity. I understand your point though.

Yes, but I would call that "for historical" reasons. We had a separation for JS in the past as well since the published their JsDocs for API & SDK on different places, but I think that's not the case anymore so we have only one link.

[jack-berg]

What do you think about:

• Remove the external javadoc redirect page at /docs/languages/java/learn-more/api
• Rename the "Record Telemetry with API" from /docs/languages/java/api-components to /docs/languages/java/api. This page becomes Java's canonical API page.

If we do this, then the only inconsistency is that java's API link is internal rather than external.

[chalin]

I'd vote against this PR. The main motivation seems to be:

Reduces the prominence of the Java Performance, Javadoc, Examples, and Registry

The prominence of those entries is already low, by the fact that they are at the end of the section ToC.

Questions:

• Why does the prominence of those entries need to be reduced further? It's not like the ToC is overpopulated atm.
• At what cost will it be done -- in both UX and infrastructure/coding "special casing"?
• What will the resulting "delta" in reduced prominence be, and is it worth it?

Here are the ToCs side-by-side to help you all get a feel:

Before	After

Pro of before: I can see all ToC entries at a glimpse.

There may be other ways to reduce the prominence of those entries, by styling them differently (e.g., faded font, italics). I'm unsure that it's worth the special casing atm, but I'm willing to entertain the discussion.

[jack-berg]

Fair points @chalin. I'm not married to this proposal I've made, but wanted to at least open up the discussion to wrap up #5211.

When I take a step back and consider my motivation here, I realize a few things:

• I don't really like 3/4 of the pages under "Learn more", but not enough to delete them.
• The "Performance" page is sort of java agent centric, but some of the ideas are applicable to the API / SDK as well. I'd really like the Java SIG (including myself) to come up with a more complete guide on how to think about performance of the SDK, including references to performance benchmarks with explanations. We're not there yet.
• The "Javadoc" link is useless now that "Manage Telemetry with SDK" and "Record Telemetry with API" exist and point to much more specific sections of the Javadoc. I wonder if we can just get rid of this page today?
• The "Examples" link is useful. No real issue with it.
• The "Registry" is a great concept, but falls short right now. I've manually added tables which I think could one day be served by the registry all over "Manage Telemetry with SDK" (for example).

If we delete "Javadoc" (and use the "Record Telemetry with API" page as the canonical java API page), and have future plans to improve performance and registry, then it becomes more palatable to not nest pages under the additional "Learn ore" section.

[trask]

The "Performance" page is sort of java agent centric

yeah, I think it's entirely about the Java agent, so we could move it to https://opentelemetry.io/docs/zero-code/java/agent/

[chalin]

In summary:

• I'm ok with what you propose: to use "Record Telemetry with API" as the api page.
• But, I'd like to strongly suggest that you a banner or note to the top of the api page giving readers who are looking for the Javadocs a direct link to the Javadocs.

More context: my original vision (coming from other projects where this is implemented), is to have api, examples, etc be (relatively) uniform across implementation languages. That being said, I'm ok with what you propose.

[svrnm]

If Performance is agent-centric we should move it to the agent for now, if this changes in the future or there is a dedicated page on the SDK we can have it as well.

Leaves us with the other pages:

• Examples: No discussion here, I agree, we keep that
• Registry: as of today this link serves the registry more than it serves the java documentation. We added those links to the language docs across all languages to promote the availability of the registry. If we find better ways in the future to integrate it, I am all in, but right now I would like to keep it.

API:

I'm ok with what you propose: to use "Record Telemetry with API" as the api page.
But, I'd like to strongly suggest that you a banner or note to the top of the api page giving readers who are looking for the Javadocs a direct link to the Javadocs.

+1 for this. At some point developers will look for the Javadoc (or the equivalent in their language) as an additional resource to learn more about the available APIs. Especially if some of them are not part of the documentation, so we should make them discoverable for them. I am fine with the proposal to remove the "Javadoc" link from the menu and have it highlighted in the "Record Telemetry with API" page, but I want to keep the link from https://opentelemetry.io/api to the Javadoc directly,
which could be https://opentelemetry.io/api/java if we want to move it out of the existing hierarchy.

It looks like we do not need the "Learn More" sub-menu for now. We can keep that in the back of our heads if the number of pages continues to grow, but I think for now let's make the adjustment discussed here and keep the remaining pages (Examples, Registry) where they are.

[trask]

At some point developers will look for the Javadoc

will they? I only ever read Javadoc inside of my IDE 🤷‍♂️

[svrnm]

At some point developers will look for the Javadoc

will they? I only ever read Javadoc inside of my IDE 🤷‍♂️

Fair point ;-)

[chalin]

At some point developers will look for the Javadoc

will they? I only ever read Javadoc inside of my IDE 🤷‍♂️

By that reasoning, we should not even be hosting API reference documentation :) ... but we do, so someone must feel that it's useful ;).

While I agree with what you say @trask (and do the same), having API reference docs hosted comes in handy now and again IMHO.

Of course, if we had access to the hosted API docs analytics, we could have a better idea about usage. Does anyone have access?

[trask]

if we had access to the hosted API docs analytics, we could have a better idea about usage. Does anyone have access?

I couldn't find anything about analytics. FWIW the https://javadoc.io site isn't anything official, it's just run as someone's personal project, scraping javadocs from maven central.

[svrnm]

if we had access to the hosted API docs analytics, we could have a better idea about usage. Does anyone have access?

I couldn't find anything about analytics. FWIW the javadoc.io site isn't anything official, it's just run as someone's personal project, scraping javadocs from maven central.

oh, for whatever reason I was under the assumption that this was something "official" we participate in. Is this a concern or is this good enough for us? As an alternative we can follow the examples of other languages and publish it to github pages/read the docs and link to that. WDYT?

I agree with @chalin that there is some value to have them, while not big advantages, still something worth to consider:

• there are people not doing java all the time, so their IDE might not be setup 100% to consume javadoc, so they can read it there
• people that write some similar code and want to take from that (e.g. they write an instrumentation library but want to see how others are structuring it)
• most importantly: search engine optimization, and that we might want to link out to the API Docs from our docs eventually, so people can look up signatures etc while reading the docs (and mybe not yet writing code)

At the end it's SIG Java's decision. If you think that this does not deliver value we can remove it

[jack-berg]

I opened #5590 as an alternative to this, and have marked this PR as a draft because I'm leaning in the direction of this new PR now.

[jack-berg]

Closing since we all seem to be in favor of #5590.