Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
wants to merge 2 commits into from
Closed

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e416838
Group java performance, javadoc, examples, registry under Learn More
jack-berg Nov 4, 2024
9bc01e2
Restore java link in apidocs.md
jack-berg Nov 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .htmltest.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,8 @@ IgnoreInternalURLs: # list of paths
IgnoreURLs: # list of regexs of paths or URLs to be ignored
- ^/api$
- ^((/..)?/docs/languages/\w+|\.\.)/(api|examples|registry)/$
# Java nests ./api/, ./examples/, ./registry/ under ./learn-more/
- ^((/..)?/docs/languages/\w+|\.\.)/learn-more/(api|examples|registry)/$
- ^(/..)?/docs/collector/registry/$
- ^(/..)?/docs/languages/net/(metrics-api|traces-api)/
- ^((/..)?/docs/migration/)?opencensus/$
Expand Down
5 changes: 3 additions & 2 deletions content/en/docs/languages/java/intro.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,8 +61,9 @@ The OpenTelemetry Java documentation is organized as follows:
Most users will use this page like an encyclopedia, consulting the index of
sections as needed, rather than reading front to back.
- **Learn More**: Supplementary resources, including end-to-end
[examples](../examples/), [Javadoc](../api/), component
[registry](../registry/), and a [performance reference](../performance/).
[examples](../learn-more/examples/), [Javadoc](../learn-more/api/), component
[registry](../learn-more/registry/), and a
[performance reference](../learn-more/performance/).

## Repositories

Expand Down
4 changes: 4 additions & 0 deletions content/en/docs/languages/java/learn-more/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
---
title: Learn More
description: Supplementary resources for the OpenTelemetry Java ecosystem
---
2 changes: 2 additions & 0 deletions content/en/docs/languages/java/api.md → .../en/docs/languages/java/learn-more/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@
title: Javadoc API reference
linkTitle: Javadoc
redirect: https://javadoc.io/doc/io.opentelemetry
aliases:
- /docs/java/api
manualLinkTarget: _blank
_build: { render: link }
weight: 210
Expand Down
1 change: 1 addition & 0 deletions content/en/docs/languages/java/examples.md → ...ocs/languages/java/learn-more/examples.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ manualLinkTarget: _blank
aliases:
- /docs/java/instrumentation_examples
- /docs/languages/java/instrumentation_examples
- /docs/java/examples
_build: { render: link }
weight: 220
---
6 changes: 4 additions & 2 deletions ...ent/en/docs/languages/java/performance.md → .../languages/java/learn-more/performance.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ title: Performance
description: Performance reference for the OpenTelemetry Java agent
weight: 75
cSpell:ignore: Dotel
aliases:
- /docs/java/performance
---

The OpenTelemetry Java agent instruments your application by running inside the
Expand Down Expand Up @@ -40,7 +42,7 @@ the Java agent.

The volume of spans processed by the instrumentation might impact agent
overhead. You can configure trace sampling to adjust the span volume and reduce
resource usage. See [Sampling](../sdk/#sampler).
resource usage. See [Sampling](../../sdk/#sampler).

### Turn off specific instrumentations

Expand Down Expand Up @@ -99,7 +101,7 @@ instrumentations, see
When troubleshooting agent overhead issues, do the following:

- Check minimum requirements. See
[Prerequisites](../getting-started/#prerequisites).
[Prerequisites](../../getting-started/#prerequisites).
- Use the latest compatible version of the Java agent.
- Use the latest compatible version of your JVM.

Expand Down
2 changes: 2 additions & 0 deletions content/en/docs/languages/java/registry.md → ...ocs/languages/java/learn-more/registry.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,4 +6,6 @@ description:
redirect: /ecosystem/registry/?language=java
_build: { render: link }
weight: 300
aliases:
- /docs/java/registry
---
4 changes: 4 additions & 0 deletions layouts/shortcodes/apidocs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,10 @@
{{ with $.Site.GetPage "/docs/languages/net/metrics-api" -}}
{{ $pages = $pages | append (dict "lang" $value "page" .) }}
{{ end }}
{{ else if eq $key "java" -}}
{{ with $.Site.GetPage "/docs/languages/java/learn-more/api" -}}
{{ $pages = $pages | append (dict "lang" $value "page" .) }}
{{ end }}
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Screenshot 2024-11-05 at 8 55 55 AM

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

{{ else -}}
{{ with $.Site.GetPage (printf "/docs/languages/%s/api" $key) -}}
{{ $pages = $pages | append (dict "lang" $value "page" .) }}
Expand Down