Adjust to move of OTLP specs into opentelemetry-proto

[tigrannajaryan]

We are moving OTLP spec from https://opentelemetry.io/docs/reference/specification/protocol/otlp/ to https://github.com/open-telemetry/opentelemetry-proto/tree/main/specification/ (pending open-telemetry/opentelemetry-proto#458).

We will need to update the documentation website appropriately (I am not sure how exactly it works today, so not sure what needs to change).

Note that only the following files are moving (not the entire directory):

specification/protocol/README.md
specification/protocol/design-goals.md
specification/protocol/otlp.md
specification/protocol/requirements.md

---

Prep

• Script adjust-pages.pl cleanup #2676
• Rename reference/spec to specification/otel and add OTLP submodule  #2677
  • Adjust name of new specs section #2701
• Fix OTel spec links to page source #2691
• Move examples into an example folder opentelemetry-proto#472
• Rename ./specification to ./docs opentelemetry-proto#469

Tasks

• Add OTLP to docs/specs #2786
• Get OTLP status from OTLP spec #2794
• Link to OTLP spec #2799
• [editorial] Drop or adjust Hugo front matter in doc pages opentelemetry-proto#479
  • Add aliases to OTLP spec pages
• Update OTLP spec to 0.20.0 #2839
• Auto check and update OTLP spec and its version #2846
• [editorial] Add Hugo front-matter for protocol to match OTLP pages opentelemetry-specification#3552
• Run prettifier over OTLP spec pages

[tigrannajaryan]

@open-telemetry/docs-approvers can you please help with this?

[svrnm]

@chalin can you give this a look? ty

[chalin]

So what is it that you would like to see on the website @tigrannajaryan and @open-telemetry/specs-approvers?

Two options come to mind and are presented below. Let me know which you prefer, or whether you had something else in mind.

1. Publish the OTLP spec separately under "Reference"

Something like this:

2. Publish the opentelemetry-proto repo OTLP spec through it's current location in the OTel spec ...

... that is, https://opentelemetry.io/docs/reference/specification/protocol/otlp/, as an override to any pages that the OTel spec might provide.

While this option is minimally disruptive, it might lead to confusion if/once #2666 lands and the spec version is visible as part of the page title and breadcrumbs. That is, we might end up with something like this:

[tigrannajaryan]

1. Publish the OTLP spec separately under "Reference"

I prefer this.

[svrnm]

I would also prefer (1), looks more user-friendly

Option (1) also has the advantage that the "Reference >" top level item is not only having one child, which is kind of confusing.

We should also add a section on the Reference page that explains what people will find here and what the differences are (not everybody is aware what OTel/OTLP stands for and what the differences are)

[austinlparker]

voted 1

[cartermp]

1 for me as well

[chalin]

@tigrannajaryan and @open-telemetry/specs-approvers I have a question for you:

The OTLP spec pages link to .proto files. Where to you want these links to point to? I see 3 options:

(a) Host the proto files on the website (as static assets) and point to the website-local files
(b) Link to proto files in the OTLP repo @Head
(c) Link to proto files in the OTLP repo at a specific tagged release

While (b) is the simplest solution, there's the potential problem that the site's OTLP docs and the repo's .proto files might not correspond to the same version. By hosting the .proto files on the website (a), we guarantee that they sync.

Option (c) also guarantees that the docs and proto files remain in sync, but it implies that we would never be able (easily) host OTLP docs other than at a tagged release.

Thoughts?

[tigrannajaryan]

Both options (a) and (c) are fine with me. I think we only want to host tagged releases on the website. Anybody who is interested in the head can work directly with the opentelemetry-proto repo.

[chalin]

Thanks for the feedback @tigrannajaryan.

Can we make some progress on getting open-telemetry/opentelemetry-proto#469 approved and merged? I'm waiting on that before I before I bring it in (though it's approved and the merge is delayed, I can implement the new directory structure in this repo, temporarily).