Ensure that all doc pages have a single source repo

[chalin]

Quoting @austinlparker in #661 (comment):

Per discussion during the last comms meeting, we'll be moving forward with the following -

1. If maintainers wish to keep the canonical copy of their docs in their SIG repo, those docs will be pulled into opentelemetry.io via submodule.
2. Otherwise, their docs will be migrated back to the opentelemetry.io repository.

This ensures that there is only ever one copy of the documentation.

We strongly recommend that maintainers choose to host the canonical copy of their documentation on opentelemetry.io repository in order to benefit from upcoming features such as internationalization and versioning.

Let's use this issue to record the decisions made (1 or 2, per SIG), track the progress for each SIG.

In some cases, SIGs have docs that aren't under website_docs and/or aren't even in a format suitable for inclusion in the website. Let's refer to this as (0). Discussions & assessment should be made re. migration to markdown so that relevant content can be published on the website either via 1 or 2.

Note: for (2), take the opportunity to clean out any markdown-link-check-* markers.

---

• Collector:
  • (2) Migrate Collector docs back to this repo #731
  • (0) Consider migrating relevant parts of the Collector docs folder
• C++: (0) has a docs folder containing .md files and some RST documentation (under public) published at opentelemetry-cpp.readthedocs.io.
• .Net (0) has a docs folder containing .md files.
• Erlang: (2) - Move website_docs back to website repo opentelemetry-erlang#280.
• Go
  • Move Go website_docs into opentelemetry.io repo #2872
  • Was (1) since Link to OTel Go website_docs via submodule #690
• Java: (1) per @jkwatson - Link to OTel Java website_docs via submodule #739
• JS:
  • (2) per @dyladan (et al.?) - Migrate opentelemetry-js website_docs back here as the single source of reference #720.
  • There is a doc folder, but it is minimal.
• PHP: (1) - Move website_docs back to website repo? (Decide by Oct 1) opentelemetry-php#423, Bring in language docs via submodules #661
• Python:
  • (1) - Migrate website_docs back to website repo? opentelemetry-python#2116
  • (0) The Python docs (from docs directory published via Read the Docs) are extensive.
• Ruby:
  • (1) - docs: Add Ruby docs as a submodule #765
  • (2) - Move website_docs back to website repo opentelemetry-ruby#1395
• Rust: (2) - Move website_docs back to website repo? (Decide by Oct 1) opentelemetry-rust#636, Delete website_docs directory opentelemetry-rust#645
• Swift: (2) - Move website_docs back to website repo? (Decide by Oct 1) opentelemetry-swift#241, Delete website_docs directory opentelemetry-swift#243

Note: This supersedes #472.

[jkwatson]

We strongly recommend that maintainers choose to host the canonical copy of their documentation on opentelemetry.io repository in order to benefit from upcoming features such as internationalization and versioning.

Who will be doing this work, though, to keep the docs up to date with i18n, etc? What is the plan for keeping the docs in sync as versions drift? I'd love to hand off the documentation duties to someone else and have it hosted in this repo, but in the past no one has done that work and things have rapidly gotten out of date. With I18N I can only imagine that will get much worse, since no person will be able to verify that things are being kept up to date.

[chalin]

Here's a concrete example of how things can go bad when we have doc pages in two repos, open-telemetry/opentelemetry-collector#4041 (comment):

Apparently, I opened a PR against the website repository (open-telemetry/opentelemetry.io#605) instead of opening one here. At some point, an automated pull request (open-telemetry/opentelemetry.io#649) between this repository here and the website repo got rid of the collector doc files I added.

[chalin]

Who will be doing this work, though, to keep the docs up to date with i18n, etc? ...

@jkwatson - OTel maintainers would be responsible for keeping the base-language docs (in English) up-to-date. Other language versions are maintained by community members. That's how things work for kubernetes.io, which has docs available in 13 languages.

Base-language maintainers can help other community members in their task of translating doc pages into other languages by following certain conventions: use "simple/international" English (e.g., by avoiding certain idioms), line wrap markdown paragraphs (this helps diff tools create more precise diffs), etc.

Not all doc pages will be available in all languages, and that's ok. Each (natural) language community decides which pages are important enough to be worth maintaining versions of in their own native language.

[austinlparker]

Unpinning this for a minute.

[jkwatson]

When Java updates the website docs in their repo, are we supposed to notify someone that a docs update is needed here?

[chalin]

@jkwatson: you can either (A) submit the update yourself (instructions follow), or (B) create an issue to notify us that the docs need updating, and which tag/commit we should use.

For (A): assuming you want to submit an update for the Java website_docs @HEAD then run the following command from a checked-out version of this repo:

$ npm run submodule:update content-modules/opentelemetry-java

Submit the resulting update via a PR.

[chalin]

All done! We'll follow through with items marked (0) in the opening comment via #833.

[chalin]

Reopening for Ruby:

• Move website_docs back to website repo opentelemetry-ruby#1395

[chalin]

Done, now that Ruby docs have moved.