Publish the specification via opentelemetry.io

[chalin]

The spec is a core OTel resource, and as such it should be published through this repo. (#833)

• Add spec pages to website
• Ensure that repository links (like Edit this page) point to the canonical source (cf. Edit/Create links for docs pages should point to authoritative sources #542)

[chalin]

Thoughts? @tedsuo @bhs @open-telemetry/specs-approvers

[bhs]

@chalin Per your note elsewhere, I will raise this with the GC today.

[bhs]

@chalin I'm live-blogging the GC meeting that's happening right now :)

You're welcome to check the recording, but the consensus is that, while we want the website to be the first port of call for end-users, we want to have a single source of truth for the spec and that must be GitHub. We will continue to push end-user getting-started docs/etc into OTel.io, though, as that will be better for the adopter community.

[austinlparker]

@bhs we could pull the specification in via submodule if we wanted to have a single source of truth.

[chalin]

@bhs we could pull the specification in via submodule if we wanted to have a single source of truth.

Right!

We're one step ahead already: the spec is already a submodule of this repo: see in https://github.com/open-telemetry/opentelemetry.io/tree/main/content-modules.

[austinlparker]

As a first step, we should add a 'Specification' category to the left nav in /docs that links to the main GitHub repo for specs.

[chalin]

@bhs - other than the obvious SEO benefit, hosting the spec on the website gives us the ability to do redirects: as the spec evolves over time, and pages or sections get moved or renamed, the website redirects can ensure that readers don't get 404s. This isn't something you get when linking directly to GH pages.

[reyang]

Couple things need to be clarified:

1. Do we only publish Stable version of specs, or we also publish Experimental specs? What to do if a spec status is Mixed?
2. Do we only publish the latest-stable version, or we publish ALL the stable versions?

[chalin]

Good questions.

I'd suggest starting with the latest-stable version (no experimental).

[lizthegrey]

I'm good with posting a copy of the spec to the website as long as it gets updated automatically, and requests to edit go to the main spec docs rather than editing a fork.

[chalin]

Thanks for the feedback @lizthegrey!

I'm good with posting a copy of the spec to the website as long as it gets updated automatically, ...

If that's what y'all prefer, it can be setup.

and requests to edit go to the main spec docs rather than editing a fork.

That's already working. For example, try the Edit page link of the following page: https://deploy-preview-866--opentelemetry.netlify.app/docs/specification/overview/

[tedsuo]

My only note (besides agreeing that it should be the latest stable version, which is released once a month) is that unless the change is a minor clarification, updating the spec is done through OTEPs.

I'm not sure adding an "update this page" conveys the gravity of making a spec change. That makes it look too much like a doc change on the website. I don't believe we should provide that feature for the spec, we are not encouraging spec PRs without issues being opened first or OTEPs being created.

[yurishkuro]

I agree with @tedsuo. It's fine to have a link to the source page in the spec, without making it an Edit link.

[austinlparker]

I chatted with bhs as well; The concern was specifically about synchronization issues. I'm going to summarize what I think the key blockers are here:

• Edit link in right sidebar should be removed.
• Automation to create new PR when tagged spec release occurs is implemented.

[tedsuo]

Looking at the layout, I also suggest that the spec should not be listed so prominently in our documentation. The spec is not intended to be end user documentation; I'm concerned that it will be distracting and confusing to list it at the top of the navigation, as that implies that it is a primary resource for end users which they need to read.

Users should never have to read the spec to make use of OTel.

[austinlparker]

Perhaps it should be under 'concepts'?

[chalin]

Looking at the layout, I also suggest that the spec should not be listed so prominently in our documentation

Ok. Under the new IA (once it is defined via #770), I would imagine that it would make sense to have a Reference section, with the spec under that.

Until we have a new IA I can I can think of a these options:

1. Not show the Specification section in the sidenav.
2. Show the Specification in the sidenav but move it towards the end of the list.
3. Add a Referrence section now (even before we have the new IA) and place the spec there from the start.

Thoughts?

[austinlparker]

I like option 3.

[tedsuo]

Option 3 sounds good

[chalin]

@tedsuo @austinlparker et al - Done:

• I've implemented option 3, and
• Replaced the "Edit page" button by a "View page source"

PTAL https://deploy-preview-866--opentelemetry.netlify.app/docs/reference/specification/

[austinlparker]

Since we've addressed the issues raised here outside of automation (which would take a bit to solve in a generalized fashion), we'll commit to a one business day turnaround for updates when new spec releases are cut from notification.

With that in mind, unless there are other blockers we'll be merging #866 next Tuesday.

[chalin]

Closed by #866