Make the spec readme the entry point for website #680

[thompson-tomo]

These changes should enable the readme to be the entry point of the public docs and the other docs in the specs to also be published

Closes: #680

[lmolkova]

@open-telemetry/docs-approvers could you please take a look?

[svrnm]

lgtm overall, but I assume we might need to do some rewiring on the oteldotio repo as well, @chalin: WDYT?

[chalin]

Hi all, I'm back.

Did you run this by @tigrannajaryan? As far as I recall, it was a deliberate decision originally to publish only the spec.

[chalin]

@svrnm @lmolkova - can we put a hold on this PR until we get feedback from @tigrannajaryan?

[chalin]

Btw, if ever the decision is made to publish more, we don't need the changes introduced in this PR. The current docs folder organization is fine.

[thompson-tomo]

So as it currently stands both the design goals & requirements docs are also published in the navigation panel of the website but rather than being integrated seamlessly into the site it is provided as a link to the github repo.

Reason for introducing the specs folder is that provides a clear mapping of what docs gets mapped into the specs folder under docs on the website, allows for docs to be excluded from the website easily & it would enable other folders to be mounted at different locations.

An example of what these other folders could be used for could be:

• A folder for describing the project for the community section
• A folder for describing how to contribute to the project for another location.

[chalin]

So as it currently stands both the design goals & requirements docs are also published in the navigation panel

Which nav panel?

[lmolkova]

According to #680 (comment) this change goes against the current practice of capturing only normative parts on the otel.io.

[thompson-tomo]

The main nav panel.

[chalin]

Oh, those are legacy entries (from the time that those pages were a part of the spec), which it might be time to remove. WDYT @lmolkova @tigrannajaryan et all? /cc @svrnm

[chalin]

Oh, those are legacy entries (from the time that those pages were a part of the spec), which it might be time to remove. WDYT @lmolkova @tigrannajaryan et all? /cc @svrnm

Come to think of it, I feel that the current situation with the legacy protocol section pages is fine as is. They redirect the reader to either the repo, or the OTLP specification, which is hosted on the OTel.io website.

I'd vote to close this PR. Thoughts @lmolkova, @tigrannajaryan, @thompson-tomo, et all?