Process for authoritative 'getting started' guides

[austinlparker]

Per comments in maintainers meeting, SIG maintainers desire a more clear process for handling website 'getting started' docs updates. Suggested process is this -

• SIG maintainers create a new website_docs directory at the root of their repo.
• The structure of this directory should mirror the subdirectory structure appropriate to that language
  • For example, Java would maintain the contents of ./content/en/docs/java in their website_docs directory, and so forth.
• Upon a release of the associated package, a member of that SIG should open a PR with the content of their website_docs directory applied to the appropriate location in the opentelemetry.io repository.
  • Alternately, they may open an issue for a comms SIG maintainer to perform this update.

cc @open-telemetry/docs-approvers @open-telemetry/docs-maintainers for discussion before 3/8 Maintainer's Meeting.

---

Edits (@chalin)

Renamed website-docs to website_docs in the text above, since that is what seems to be used across the language repos.

Here is a list of the code repos with an indication of their status (as of 2021/09/25):

Repo*	Has website_docs folder	Has docs-update GH Action	Note
opentelemetry-collector	☑️	☑️	Docs are back in this repo - #4042
opentelemetry-cpp	✖️	✖️	Docs in this repo. Doc update via documented process.
opentelemetry-dotnet	✖️	✖️	Docs in this repo. Doc update via documented process.
opentelemetry-erlang	☑️	☑️*	Docs are back in this repo: #801. *open-telemetry/opentelemetry-erlang#285
opentelemetry-go	✅	✖️	Setup as submodule in this repo by #690
opentelemetry-java	✅	☑️*	Setup as submodule in this repo by #739. *open-telemetry/opentelemetry-java#3690
opentelemetry-js	☑️	✖️	Docs are back in this repo - #722
opentelemetry-php	✅	☑️*	*open-telemetry/opentelemetry-php#435
opentelemetry-python	✅	☑️*	*open-telemetry/opentelemetry-python#2171
opentelemetry-ruby	✅	✖️	Setup as submodule in this repo by #765
opentelemetry-rust	☑️	✖️	Docs are back in this repo - open-telemetry/opentelemetry-rust#645
opentelemetry-swift	☑️	✖️	Docs are back in this repo - open-telemetry/opentelemetry-swift#243

*The repo link, is the link to the PR that created the website_docs folder.

[jkwatson]

What format would these docs be in?

[austinlparker]

Markdown. The only real requirement is that they have a block at the beginning like so, with appropriate frontmatter (see https://gohugo.io/content-management/front-matter/) -

---
title: "Automatic Instrumentation"
weight: 3
---

They can also use any other features available to the docs site, such as tabs by calling the appropriate blocks (as seen in the Erlang/Elixir docs) -

{{< tabs Erlang Elixir >}}

{{< tab >}}
$ rebar3 new release otel_getting_started
{{< /tab >}}

{{< tab >}}
$ mix new otel_getting_started
{{< /tab >}}

{{< /tabs >}}

[tedsuo]

How should links be handled?

[austinlparker]

Absolute links should be fine irregardless. Relative links should also be fine, as Hugo defaults to not canonifying relative links, and it tends to be kinda smart about it.. for example, in /content/en/docs/java/getting_started.md there's a link to [/docs/java/#releases-1]. Hugo will do the right thing for [../#releases-1] as well (the link it creates in both cases will be to <protocol>://<host>:<port>/docs/java/#releases-1)

The only thing I can see tripping people up is creating relative links to content outside of the website_docs directory.

[austinlparker]

I'm going through and making PR's mirroring the website docs to SIG repos today.