Improve documentation so that more can be published

[thompson-tomo]

I want to have all the OTLP spec docs published on the website rather than having links to github and by adopting the new structure we can get more docs logically included.

Allowing for the sub folder solution means down the track contributing docs etc could be published.

[chalin]

Hi @thompson-tomo, can you provide some more context and motivation for this request?

On the website under Docs > Specs we have, up until now, only published the specs themselves. That is only formally binding parts. For a change that was done in support of this see:

• Move examples out of spec into an examples folder #471

/cc @svrnm @lmolkova @tigrannajaryan

[chalin]

And, as I mention in #681 (comment), we don't need to reorganize the docs folder to publish more content.

[thompson-tomo]

Hi @chalin as mentioned in other comment, there is 2 additional pages currently published via links to github on the website. This is mentioned in the issue description.

As mentioned above split is so that contributing docs could be published which makes no sense to be under specs.

[chalin]

there is 2 additional pages currently published via links to github on the website.

Can you show me (via a screenshot) what you mean by this?

Unless there is a change in policy, https://opentelemetry.io/docs/specs/ only hosts spec pages that are normative. For everything else (requirements, design docs, examples), we direct the user to the repo.

AFAIK, the only page that is normative on the proto repo is the page https://github.com/open-telemetry/opentelemetry-proto/blob/main/docs/specification.md.

[thompson-tomo]

Here you are @chalin

[chalin]

@thompson-tomo - oh, those are legacy pages, I'd forgotten about them, but thanks for pointing them out.

As I was working on open-telemetry/semantic-conventions#2802 (comment), I realized that "https://opentelemetry.io/docs/specs/ only hosts spec pages that are normative" isn't quite true. There are non-normative semconv pages, for example.

So, if the maintainers of this repo (which I understand from the repo README is the @open-telemetry/technical-committee such as @lmolkova and @tigrannajaryan) agree to also have the design goals and requirements published on the website, then I'll make the necessary adjustments to the OTel.io repo so that all pages under https://github.com/open-telemetry/opentelemetry-proto/tree/main/docs get published.

Thanks for your patience in getting back to you (I though I had responded, but I must have forgotten to save my comment).

[thompson-tomo]

No worries @chalin let's see what they say. If we choose not to publish perhaps we remove the links from the navigation bar.

[chalin]

Pinging @open-telemetry/technical-committee @lmolkova @tigrannajaryan: any opinion on this? Shall we leave things as they are, or try to get the design and requirements pages published to the website too?