Bring in language docs via submodules

[chalin]

Hi all. I see that you've already spent some time fleshing out a Process for authoritative 'getting started' guides #472, which is based on file copying.

I'd like to suggest that we keep things DRY, by using submodules instead. I've implemented that successfully in other projects. (Btw, we're already using (recursive) submodules for Docsy.)

We can do this incrementally, and for one language to start off with, if you'd like to test the concept.

Thoughts? @tedsuo @austinlparker @mtwo @flands

---

Disadvantages of file mirroring and copying:

• We loose true edit/blame history
• There's the risk of edits being done in the wrong place (since files are present in two repos)
• There's potential confusion of where to open issues (again, since files are present in two repos)

Advantages of using submodules (other than the counterpart of the disadvantages listed above):

• Website maintainers can bring in doc updates from all language repos with a single command

---

• Go - Link to OTel Go website_docs via submodule #690
• Java - Link to OTel Java website_docs via submodule #739
• PHP - Link to OTel PHP website_docs via submodule #804
• Python - Link to OTel Python website_docs via submodule #805
• Ruby - docs: Add Ruby docs as a submodule #765

Note: #542 must also be implemented for these languages.

[chalin]

All: a first PR implementing the submodule approach recommended in this issue is #690.

[dyladan]

I tried to implement this for JS and I'm not sure I fully agree with this approach. Here are the problems I ran into immediately:

• The build process doesn't run in the source repo. If I make a change to the JS doc which breaks the website build, there is no way for me to know until much later. Because of the way link resolution works, links that appear valid in markdown are broken on the website build.
• The submodule still needs to be updated, so this doesn't really prevent the need to make PRs on this repo.

I would almost rather see the website docs removed entirely from the client repositories and moved into this repo. Then we link to the website from the readmes of each project and this repo becomes the authoritative source for documentation. We can use some action like https://github.com/open-telemetry/assign-reviewers-action to ensure language maintainers don't miss when their docs are updated.

[austinlparker]

Couple of notes...

First, I generally agree with @dyladan that website docs should live entirely in this repository. That's how it was for many months! Maintainers of other SIGs disliked this approach, as it caused 'drift' between documentation that they were writing in their repositories and documentation on the website. When we proposed moving docs per-language into the language repositories, submodules were considered and rejected for several reasons:

• Submodules are finickly and I dislike using them
• They require website maintainers to know the correct commit/tag to pull from in order to get the 'correct' docs version on the site. Running an update on each build (or nightly, whenever) wouldn't necessarily get the 'right' version of the docs either.

The 'push' model of having docs mirrored was proposed and agreed to by all maintainers several months ago. While it's obviously not a perfect solution, it's the one we built up a consensus around. @chalin your summary of the disadvantages is spot-on, and most of them have already happened, but the only real option as I see it is to continue to allow maintainers to "push" PRs here with updates or go back to the well and try to re-migrate docs back into this repo.

[dyladan]

Another disadvantage of submodules that austin didn't mention is that it depends on external repositories not merging changes which break the website build, something that is very easy to do. Not all valid markdown compiles into a working site. For an example, see the most recent JS docs update where the valid relative links of the form [text](../relative_path.md) caused the build to fail even though it worked perfectly fine in the github markdown UI.

Personally, I see huge advantages of having only one place where the documentation resides. I think my proposed solution would be to have SIG repositories have an extremely simple "getting started" section on the README which does the bare minimum to get autoinstrumentation working in the most common case. Anything more advanced than that should link out to the website which may contain significantly more information and all of that should live in this repository.

[chalin]

Thank you both for your feedback. I'm not wed to using submodules. The most important thing IMHO is to avoid having files reside in two repos.

Personally, I see huge advantages of having only one place where the documentation resides.

I agree, and this brings up another point: IMHO we don't need to have the same solution implemented for all languages. (In fact, we don't currently -- there seemed to be pushback on the mirroring scheme, see the table in #472 (comment)).

[chalin]

FYI, another example of how having files into two places can go wrong: #709.

[austinlparker]

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.

[bogdandrutu]

Collector wants the docs in the website if that simplifies things

[austinlparker]

Per @jkwatson, java will keep their docs in their repo, so we'll need to submodule that @chalin

[chalin]

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.

Let's use #730 to track the decision and overall progress for each SIG.

[chalin]

All done!
#542 will be next.