Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Move Java docs into this repo #989

Closed
3 tasks done
Tracked by #833 ...
chalin opened this issue Dec 16, 2021 · 21 comments · Fixed by open-telemetry/opentelemetry-java-examples#9
Closed
3 tasks done
Tracked by #833 ...

Move Java docs into this repo #989

chalin opened this issue Dec 16, 2021 · 21 comments · Fixed by open-telemetry/opentelemetry-java-examples#9
Labels
cleanup/refactoring e0-minutes Effort: < 60 min IA Information architecture rework p1-high

Comments

@chalin
Copy link
Contributor

chalin commented Dec 16, 2021

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)


@austinlparker
Copy link
Member

cc @jkwatson @anuraaga

@jkwatson
Copy link
Contributor

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
Copy link
Contributor Author

chalin commented Dec 17, 2021

@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:

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
Copy link
Contributor

@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
Copy link
Contributor

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
Copy link
Contributor Author

chalin commented Dec 17, 2021

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
Copy link
Contributor

hdost commented Dec 18, 2021

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
Copy link
Member

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
Copy link
Member

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
Copy link
Contributor

cartermp commented Dec 20, 2021

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
Copy link
Contributor Author

chalin commented Dec 20, 2021

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
Copy link
Contributor Author

chalin commented Dec 20, 2021

Thanks for sharing your perspective @cartermp!

@anuraaga
Copy link

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
Copy link
Contributor Author

chalin commented Dec 21, 2021

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
Copy link
Member

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
Copy link
Contributor

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
Copy link
Contributor Author

chalin commented Dec 21, 2021

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
Copy link
Contributor

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
Copy link

@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
Copy link
Contributor Author

chalin commented Dec 22, 2021

@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
Copy link
Contributor Author

chalin commented Jan 13, 2022

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
cleanup/refactoring e0-minutes Effort: < 60 min IA Information architecture rework p1-high
Projects
None yet
Development

Successfully merging a pull request may close this issue.

7 participants