Documentation and guides

[arielvalentin]

https://opentelemetry.io/docs/ruby/ does not have much detail on the main site other than status and links to this repository.

What expectations do we have around how much detail goes into external vs internal documentation?

Do we prefer example code vs documentation?

Should we contribute to hipster-shop instead of maintaining examples in the repository?

Related Issue

• Documentation Tracking Issue #775

cc: @open-telemetry/ruby-approvers

[fbogsany]

What expectations do we have around how much detail goes into external vs internal documentation?

In general, the opentelemetry.io docs should be higher level ("Getting Started"), with references to more detailed API docs and examples. The doc structure comes from #691:

When a release occurs and these docs are updated, please make an issue or PR mirroring them to their appropriate location in the website repo (https://github.com/open-telemetry/opentelemetry.io/tree/main/content/en/docs/ruby).

The docs for opentelemetry.io live here: https://github.com/open-telemetry/opentelemetry-ruby/tree/main/website_docs

Internal documentation should be more detailed, and clearly aimed at different audiences/tasks:

• Contributor
• Maintainer / approver
• Auto-instrumentation author
• Resource detector author
• Operator
• Library author instrumenting their library
• Application author instrumenting their application
• Release process
• ...

Do we prefer example code vs documentation?

Why not both? 🤷 In general, we should always be aware of "cargo culting" with examples - folks looking for a quick win will blindly copy code and likely won't pay attention to suggestions in comments or associated docs. We should strive to have examples work out of the box for typical deployments - environment variables should be used to configure them rather than hardcoding configuration in the example code.

Should we contribute to hipster-shop instead of maintaining examples in the repository?

We should do both. The hipster-shop is a good test bed for multi-service and multi-language deployments, but it is a more complicated example and not immediately approachable for beginners. We need some good standalone examples here.

[ahayworth]

Should we contribute to hipster-shop instead of maintaining examples in the repository?
We should do both. The hipster-shop is a good test bed for multi-service and multi-language deployments, but it is a more complicated example and not immediately approachable for beginners. We need some good standalone examples here.

I agree with this. They serve different purposes; and you can re-use parts of hipster-shop in a pinch, but it'd be better / more clear for folks to have focused ruby examples that are outside of the multi-service demo environment.