-
Notifications
You must be signed in to change notification settings - Fork 1.2k
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
Move Java docs into this repo #989
Comments
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. |
@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. |
@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. |
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. |
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):
As for your comment:
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? |
Would it be possible that regardless of where Javadocs end up that there could be a doc test in the Java side? |
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? |
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. |
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:
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. |
Other advantages for having the docs here:
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. |
Thanks for sharing your perspective @cartermp! |
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 |
Thanks for the honest feedback @anuraaga!
I'll gladly help streamline that process. |
Agree with @anuraaga. It's important that we have a place to put working code that incorporates 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. |
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? |
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. |
@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. |
All done. Thanks to all for your participation in the discussion. |
Originally posted by @austinlparker in #978 (comment)
website_docs
folder from https://github.com/open-telemetry/opentelemetry-java Delete website_docs since it has moved opentelemetry-java#4019website_docs
folder from https://github.com/open-telemetry/opentelemetry-java-docs - Delete website_docs directory opentelemetry-java-examples#9The text was updated successfully, but these errors were encountered: