Move Java docs into this repo

[chalin]

I agree that having code samples in this repository doesn't make a ton of sense, but my understanding that the rationale from maintainers to keep docs + samples in the main repo was to ensure they were updated alongside the SDK releases. If that isn't a concern any more, and they're going to be divorced from it anyway, then I'd strongly urge for all documentation to be migrated directly into this repository, with a separate code sample repository being maintained.

Our eventual goal would be to migrate all docs to the website at the end of the day (aside from things that don't make sense, like auto-generated API docs or things that require language-specific tooling; javadoc, et. al.) so that we can enable versioning of the documentation and promote the website as a "one stop shop" for OTel docs.

Originally posted by @austinlparker in #978 (comment)

---

• Move doc files into this repo - Bring java docs home #1002
• Delete website_docs folder from https://github.com/open-telemetry/opentelemetry-java Delete website_docs since it has moved opentelemetry-java#4019
• Delete website_docs folder from https://github.com/open-telemetry/opentelemetry-java-docs - Delete website_docs directory opentelemetry-java-examples#9

[austinlparker]

cc @jkwatson @anuraaga

[jkwatson]

If we move some docs into here, and some docs into the common java docs repo, and we have some docs in the individual repos, then we'll have 3 places that have to be updated. I think that is too much for maintainers to worry about.

[chalin]

@jkwatson - You are right that having docs spread out is a headache for maintainers. Now multiply that by 11 languages and you'll get a better appreciation of the maintenance challenge for this repo.

As a language SIG you have the liberty to organize your source code as you see fit, which includes moving example code into a separate repo (which, if I understand correctly, is one of the objectives behind the creation of your new repo).

The Comms team's mandate includes ensuring that docs/website maintenance remains manageable for the entire community -- all 11 languages. We're doing our best to accommodate language SIGs, but we set limits so that we can keep our sanity. These limits are as follows:

• Our main objective is to repatriate all "non-API docs" (#833, also see note 1 below) into this repo. Most of the docs are here, but some still need to be moved.
• We make an exception for language SIGs that prefer to colocate main-repo code and docs. This is the only exception.

If you've decided that the Java docs don't need to be colocated with the main-repo code, then those docs come back here. Given this broader perspective, I'm hopeful that you'll understand our reasoning.

[jkwatson]

@chalin Were these decisions made after consulting maintainers, or completely ad-hoc without consultation? OTel maintainers are generally over-committed already, so before you make decisions that will impact us, it's probably a good idea to talk to us about it.

[jkwatson]

I believe that having 2 java repositories consolidate their documentation into 1 docs repository makes the docs team's job easier, doesn't it? Now you only have 1 place to sync with, rather than the 2 you would otherwise have.

[chalin]

I totally get being over-committed already.

I do believe that @austinlparker brought up the subject at a maintainers meeting. For our decision, see #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.

As for your comment:

I believe that having 2 java repositories consolidate their documentation into 1 docs repository makes the docs team's job easier, doesn't it? Now you only have 1 place to sync with, rather than the 2 you would otherwise have.

Oh, so you're consolidating all the Java docs under the new repo?

Btw, even if the Java docs are not in this repo, Java maintainers need to be mindful of not breaking the docs build. Having the docs elsewhere makes that much more difficult to ensure.

Ok, I'll see if @austinlparker is available to discuss this next week. Maybe you'd be available too?

[hdost]

Btw, even if the Java docs are not in this repo, Java maintainers need to be mindful of not breaking the docs build. Having the docs elsewhere makes that much more difficult to ensure.

Would it be possible that regardless of where Javadocs end up that there could be a doc test in the Java side?

[austinlparker]

If we move some docs into here, and some docs into the common java docs repo, and we have some docs in the individual repos, then we'll have 3 places that have to be updated. I think that is too much for maintainers to worry about.

I want to point out that what we've tried to do since the beginning was have all docs in a single place, but some maintainers (including Java) demurred because they believed having docs 'close' to the SIG repo would improve doc quality. And yes, it's been brought up several time at maintainer meetings.

I get that maintainers are over-subscribed, but as the project expands then it becomes less and less maintainable for every SIG to make their own individual decision about where to put documentation and makes it significantly harder on docs contributors who, often, work across languages.

More bluntly, why should the convenience of the Java maintainers be prioritized over the convenience of general contributors, or the onboarding experience for new project users?

[austinlparker]

In the interests of getting the required updates done before the holidays, we'll go ahead and submit PR's to fix the links on the submodule side and pull it into the website.

[cartermp]

My perspective - as someone who's been starting to add docs for each language, and plans on doing that for quite a while - is that hopping around between different repos is much more challenging.

For example:

• Policy requires multiple maintainer approvals, which means turnaround tends to be longer because folks are busy maintaining the SDK itself - go, python repos so far
• PRs that have been approved by maintainers but are blocked until the unrelated build issue is resolved - go, ruby repos so far
• Differing approaches to IA and what to emphasize limiting what can be contributed - ruby repo so far
• No link validation for docs in an SDK repo - go repo so far

So far the Java docs repo has been pleasant to contribute to, since it's simple and folks are quick to approve and merge if the content is good. I've appreciated how responsive folks are. But in the general case, it's already caused some stutters in the process with 3 language repos and it's likely to cause more.

I can work with either approach, but would prefer a docs repo to be the source of truth, at least for concepts that are stable in the SDK.

[chalin]

Other advantages for having the docs here:

• You can submit a PR and know if you've broken the build, and if so, fix the problem.
• PRs automatically get a deployed preview. That's (very) challenging to get when docs are pulled in from another submodule.

If you're modifying docs in a submodule, it's easy to break the build, for example: open-telemetry/opentelemetry-java-examples#7. Now that's a pain, because the person who updates the submodule, will probably not be the person who make the doc changes, and so, for non-trivial cases, it can require tracking down the original author and having them submit changes. As @cartermp points out, that decouples the cost & effort of making doc changes.

[chalin]

Thanks for sharing your perspective @cartermp!

[anuraaga]

FWIW, I think the java maintainers, at least myself, don't put enough time into docs to have a huge say in the matter :P We needed to have a repo with shared docs because of how related SDK and instrumentation functionality is and came up with the opentelemetry-java-docs repo, but in reality I think it's OK for that to only focus on code samples. I don't see a problem from a maintenance perspective from having the website docs managed here, especially if someone can help contribute tooling that creates a PR to this repo automatically during our release process updating version numbers, like this one

https://github.com/open-telemetry/opentelemetry-java/pull/3934/files#diff-85b479b7a0513e35b12d73774cea2cf9cefedc41900ad8b55949cb7d3faa9ffe

[chalin]

Thanks for the honest feedback @anuraaga!

I don't see a problem from a maintenance perspective from having the website docs managed here, especially if someone can help contribute tooling that creates a PR to this repo automatically during our release process updating version numbers

I'll gladly help streamline that process.

[jack-berg]

Agree with @anuraaga. It's important that we have a place to put working code that incorporates opentelemetry-java-instrumentation, the opentelemetry-java, and opentelemetry-contrib. Having good code examples on topics that are cross cutting is important to adoption.

The docs will end up referencing these code samples, and ideally they would be located in the same place. I don't think the docs repo is a good place for the code samples to live, since there's decent amount of build tooling that comes with that, and having N languages worth of build tooling live in the docs repo (assuming other languages will face similar challenges) seems challenging.

Keeping the docs separate with relevant links to the code samples seems like a fine compromise.

[jkwatson]

Keeping the docs separate with relevant links to the code samples seems like a fine compromise.

I worry about chicken/egg situations where changes to the code samples will break documentation links until the documentation can be updated. How can these two be coordinated if they are kept in separate repositories?

[chalin]

Only internal links are checked as part of CI (because external link checking isn't fully configured yet -- though you can check external links manually) so, there's no risk of breaking the docs build if code changes are committed first, which is what I've seen happen most often.

[jkwatson]

Only internal links are checked as part of CI (because external link checking isn't fully configured yet -- though you can check external links manually) so, there's no risk of breaking the docs build if code changes are committed first, which is what I've seen happen most often.

I'm not worried about breaking the docs build but the currently in-place docs, since changes to a far-flung repository will create broken links with no one having any idea that it's occurred until a user complains about it.

[anuraaga]

@chalin If it's possible for the docs build to generate a list of referenced external URLs, I think we could add a link checking job to the code samples repo when making changes to it. Does that sound possible?

[chalin]

@chalin If it's possible for the docs build to generate a list of referenced external URLs, I think we could add a link checking job to the code samples repo when making changes to it. Does that sound possible?

Yes! I've been working on such a solution (part-time) since the spring. I'll give it more priority in 22Q1.

[chalin]

All done. Thanks to all for your participation in the discussion.