Should examples exist in this repo?

[codeboten]

Component(s)

No response

Describe the issue you're reporting

I'm wondering with all the changes to centralize documentation in the OpenTelemetry website if the examples directory still makes sense to keep in this repo.

[mx-psi]

I am in favor of getting rid of it and hosting things in opentelemetry.io

@tiffany76 what do you think?

[atoulme]

No, examples should not be in this repository. We have the demo and opentelemetry.io.

[tiffany76]

Example	Primary subject
couchbase	Component (Prometheus receiver)
demo	Demo of Collector
fault-tolerant-logs-collection	Component (filelog receiver)
kubernetes	Deployment
logline-filtering	Component (filelog receiver)
nomad	Deployment
secure-tracing	Security

I agree these examples are intended for operators/end users and would suit the website's audience.

In the case of the component examples, the problem is that the website does not currently document contrib (or core) components, except within the limited scope of a Kubernetes deployment. An old discussion from the .io repo raises the issue of pulling in component READMEs from the core and contrib repos to the website registry for the sake of discoverability, but as of now, no decision has been made.¹

If and until this content refactoring is implemented, I think the component examples would seem "orphaned" on the website. For instance, our docs would be incomplete if we tell users how to filter logs using the filelog receiver but don't tell them any of the other configuration options. If we agree moving the component examples to the website is not an option right now, I think it makes sense to relocate them to the corresponding component's directory. If I was searching for example configs for a component, that's probably where I would look.

Regarding the other types of examples:

• We can probably find a good spot on the website for the Kubernetes deployment demo and the secure tracing example.
• I'm not sure if the Nomad demo is something we'd put on the website, given our affiliation with CNCF and Kubernetes. Happy to take direction from the docs maintainers on this one.
• Does the Collector demo example duplicate some aspect of the website demo or is it supplemental? I haven't had a chance to run it to compare.

Since I'm new to these discussions and don't have all the history, I'd like @open-telemetry/docs-approvers to provide their input as well.

¹ There might be solutions to this problem that also meet the leadership team's requirement to keep documentation close to codeowners, but I think we can discuss implementation after we first reach a decision on whether these docs should live on the website at all.

[github-actions]

This issue has been inactive for 60 days. It will be closed in 60 days if there is no activity. To ping code owners by adding a component label, see Adding Labels via Comments, or if you are unsure of which component this issue relates to, please ping @open-telemetry/collector-contrib-triagers. If this issue is still relevant, please ping the code owners or leave a comment explaining why it is still relevant. Otherwise, please close it.

[mx-psi]

I'd like @open-telemetry/docs-approvers to provide their input as well.

Any input from your side, @open-telemetry/docs-approvers?

Should we create separate issues for the individual examples?

[svrnm]

What we currently see emerge from docs site is that we want to have code live in the SIG's repos with all the tests and linting and we use tooling to pull in source code into the documentation. We have some ongoing experiments with Go & Java, and I would assume the same could apply to these examples. We could write some prose around them in the docs and then pull the code from here.

The only issue I see is that some of these examples are fairly complex and are related to the Tutorials Discussion which still is not concluded

[mx-psi]

Okay, that seems reasonable. Should we close this as wontfix then, or should I wait until the tutorials discussion is resolved?

[svrnm]

yes, I think that's the best approach