Automation between OTel repos

[julianocosta89]

Desired feature or idea: What would you like to see happen?

As the Collector moves to stable, the maintainers of it are defining requirements to move a component to different stability levels.
As of today, most of the components docs are under each component in a README or example file.

While discussing with @mx-psi in this issue, I've mentioned that it would be great to have documentation under the official OTel docs: opentelemetry.io.

The problem is that this would create an extra burden for codeowners and maintainers to keep track of 2 repos and making sure they are always in sync.

The actual feature request

Ideally, codeowners would write down the docs in the Collector repo in some sort of markdown, or yaml, or whatever we define, and the OTel docs page would render whatever is in this file in an user friendly way (not all users like reading READMEs and files in the GH repository).

[svrnm]

Is this strictly for collector components and how we keep their docs in sync with the website or is this a larger request, since you made the following comment in the linked issue:

I also think having 2 repos is a pain. We are currently struggling with that in the Demo repo, and I feel that this would also impact the documentation of the Collector components.

If it is around collector components, this is from my point of view a registry problem, and I tried to address some of that in this proposal: Registry Data Quality Improvements. I am more than happy to enable this, but we (SIG Comms) do not have the capacity to do that, that's why I put out that proposal: if there is a group of people that want to tackle the registry problem and run with it, I would be delighted, until then it's a gradual progress.

If it is around a general request to be able to sync docs from a SIG's repo to the website repo, I would also be more than happy to reenable that, but there are once again a set of road blockers that require effort that is way beyond the capacity that our SIG has. I write "reenable", because there is some history to that. Also, we have some automation between repos already, for syncing versions, specs, some community pages.
Based on that experience I can scope out some of the challenges we would need to get out of the way, to enable that:

1. hugo requires the markdown files to have a frontmatter, and it allows the use of shortcodes to format things in a certain way. It also renders some things slightly differently than github, so if a SIG wants to host their docs on their own we would either need to provide some tooling to convert the markdown files (as we do it for the spec right now) or the SIG needs to ensure, that the markdown files are in the required format, see this old state of the go repo
2. We run a lot of linting and formatting over the markdown files to ensure some quality standards across files (link checkers, spell checkers, text rules, etc.), if the docs would live in the repo of the SIGs we would need to make sure that those checks are executed accordingly. We also provide previews via netlify, which you would need to enable on each repo as well via github automation.
3. I would assume that cross-linking from one section of the docs (say demo) to another (say collector) will need some special treatment as well. Probably a sub-problem of (2).
4. Submodules! Although we have improved the situation significantly with some tooling & automation, we historically had a lot of PRs that broke because of outdated submodules or people doing some odd merging and rebasing and screwing up their commit history. Also, there needs to be some automation to keep them updated while docs in the repos evolves. This is what you ask to have a solution for. Again, something that requires github automation to be created.
5. This does not apply for the collector, the demo or the operator documentation, but for the language implementations: a major reason why we moved away from the docs in the SIG repo was that the docs across languages were inconsistent, outdated, sometimes incorrect and often lacking details. We (OpenTelemetry) propagate that idea that there is a spec for otel concepts, which is implemented the same across languages, so also the docs should be the same across languages for those otel concepts, and only some parts of it should be "language specific". This worked fairly well, but we are also running in issues with that and are currently trying to fix some of that, see this discussion and this proposal. The big downside I see these days with that decision, is that we now are in a "docs as a service" state, and some SIGs do not feel responsible for keeping the docs on the website up-to-date. At the end this is a non-technical problem, as we (OTel maintainers) need to agree on how our documentation should look like moving forward.
6. Finally, while it is a burden for maintainers and codeowners right now to keep track of 2 repositories, doc maintainers & approvers who provide copy editing for docs would need to keep track of ~20 repositories, if we move docs down to the repositories. I don't have a good answer here.

After dumping that pile of problems on you, let me repeat the following: I would love to see this implemented that way, as it would push back the primary ownership of the docs to the SIGs where it (imho) belongs.

[julianocosta89]

The big downside I see these days with that decision, is that we now are in a "docs as a service" state, and some SIGs do not feel responsible for keeping the docs on the website up-to-date. At the end this is a non-technical problem, as we (OTel maintainers) need to agree on how our documentation should look like moving forward.

I think this is the main issue.

Maybe we could start in a slower pace. Something like, whenever file x is touched a new issue is created in the docs repo, and the user that changed gets assigned to the issue.
The problem is that AFAIR in docs we do not assign issues to users 😬 (anyways this wouldn't ensure people would actually do what they need to do).

Regarding the Registry, I'm not sure. I don't think it actually fits the Registry.
The Registry is great to have an overview of what is available out there, but, me personally, I've never looked at it looking for documentation on how do use a component. Still, if we implement it in that way, that may change how people use it (me included).

Personally, I'd love to see something like this in the docs:

• Collector
  • Receivers
    • OTLP
    • ...
  • Processors
    • TranformProcessor
    • ...
  • Exporters
    • OTLP
    • ...
  • Connectors
    • SpanMetrics
    • ...

That's A LOT of work, and I don't think it should be responsibility of the SIG Comms to keep it all up-to-date.

[svrnm]

Maybe we could start in a slower pace. Something like, whenever file x is touched a new issue is created in the docs repo, and the user that changed gets assigned to the issue.
The problem is that AFAIR in docs we do not assign issues to users 😬 (anyways this wouldn't ensure people would actually do what they need to do).

The "do not assign" policy is especially relevant for people that show up and want to have an issue assigned to them and then never do something, or just use it as reference that they "contribute to OSS". That's why it is limited to people who didn't contribute to otel yet, which is not the case anymore for someone who has touched a file in the demo repo.

So to make it short: if the Demo SIG wants to have an automation for that, I have no issue with that (@open-telemetry/docs-maintainers wdyt?). My requirement would be that it is then assigned to someone and labelled properly (sig:demo, etc.), so we do not have to do extra traige

Regarding the Registry, I'm not sure. I don't think it actually fits the Registry.

I want to have it in the registry, because we can build pages from there for the components in a data-driven way best (e.g. via Content Adapters). I actually tried this once locally and it "works" to build a hierarchy as you described it, but this will create HUNDREDS of pages, which will massively slow down the build process and also since hugo is a static page generator if someone goes to docs.opentelemetry.io that navigation structure will be preloaded.

So there is some work that needs to be done to make this possible.

That's A LOT of work, and I don't think it should be responsibility of the SIG Comms to keep it all up-to-date.

ACK