website_docs: push or pull?

[chalin]

@MrAlias @Aneurysm9: with open-telemetry/opentelemetry.io#690 merged, I can now sync this repo's website_docs regularly (once a day/hour/etc), pulling in changes to the website repo.

This means that the Go docs published on the website would reflect website_docs "@HEAD", without any intervention on your part. Is that what you'd like (where the website repo polls & pulls in website_docs changes), or would you prefer being in control of when the docs page changes are pushed to the website (by filing a PR or an issue over the website repo)?

[MrAlias]

It would be ideal if we could have the website docs track the latest release. That way unreleased changes wouldn't confuse new users looking at the docs and their wouldn't be added workflow for us to update things. Is it possible to do this? E.g. track the latest semver release?

Also, is there a way for users to see old versions of docs? Like old relases?

[chalin]

Hi, just a quick note to let you know I'm mostly OOO this week. The short answer is: yes we can track the latest release. The long answer ... will come later 😄.

[chalin]

At the maintainer's meeting this past Monday @austinlparker explained that SIGs now have a choice between hosting their docs in the website repo (allowing support for internationalization and doc versions), or having their docs published via a submodule link to the SIG's website_docs folder.

For details, see open-telemetry/opentelemetry.io#730.

Before addressing your questions from earlier, I'll like to know what your (Go SIG's) choice is, given the pro's and con's of each approach.

[MrAlias]

For posterity, the solution we have landed on is to explicitly push docs changes from this repository into the main website by updating the submodule of this respoitory in the main opentelemetry.io repository.