Nice to have: a tutorials section on opentelemetry.io where folks can easily access tutorials

[avillela]

See Slack conversation reference here

TL;DR: It would be nice to see a compilation of OTel tutorials on opentelemetry.io that are easy for folks new (and not so new) to OpenTelemetry to easily access. We have a combination of existing tutorials on the site, along with blog posts, and it would be nice to have a "one-stop shop" for all of these.

Very relevant challenges outlined by @svrnm:

• We try already very hard to make our docs “hands-on”, i.e. we want to have a “getting started” and then each section should eventually build on top of it by reusing that code example. Even if I go down to the operator, my preference would be reusing the same example apps and learnings from the langauge specific and collector sections. By creating a “tutorial” section we create a zoo of different “stories”
• Blog posts have one big advantage, which will be a disadvantage if we turn them into official “tutorials”: we treat blog posts as “point in time” publications, so if any of those blog posts stops working for any updates to the tooling used, we are OK with that. If we turn them into official tutorials, we have to make sure they are up-to-date
• People will prefer writing a tutorial over contributing to the docs, since it is easier (they do not have to work on anything legacy) and we always have to carry the risk that they bring v1.0 but never do a version 1.1 etc as we need it to be updated.

Major concern: maintanance, as the SIG is way too small to handle that right now. Nice to have: having a place where people can say “I want to do task X” and then they get all the content from all the pages they need for that.

Recent blog posts with content that might be candidates:

• https://opentelemetry.io/blog/2024/otel-errors/ -> Concept page about “What are errors/exceptions”
• https://opentelemetry.io/blog/2024/scaling-collectors/ -> the ansible module would need to be donated to the community (which we asked for), then this could easily live under collector docs
• https://opentelemetry.io/blog/2024/getting-started-with-otelsql/ -> interesting one, would be great for Go > Libraries, but unfortunately the instrumentation library is not “official”
• https://opentelemetry.io/blog/2024/otel-collector-anti-patterns/ -> collector docs
• https://opentelemetry.io/blog/2023/any-metric-receiver/ -> collector docs
• https://opentelemetry.io/blog/2023/logs-collection/ -> great point in time article, but now python should have a proper documentation of logs
• https://opentelemetry.io/blog/2023/synthetic-testing/ -> collector docs

Re: blog posts, can we take an inventory of existing ones that are candidates for being absorbed into documentation? For those that are more point-in-time, can we add tags to the blog posts so that they’re at least easier to find?

[hughesjj]

This would be amazing. FWIW on our splunk distro we have a bunch of things in the examples folder, but it would be much better for them to flow as a tutorial rather than just a README + docker compose + sample file imo

[svrnm]

Re: blog posts, can we take an inventory of existing ones that are candidates for being absorbed into documentation?

Using the list I provided already / that you copied as a starting point:

• https://opentelemetry.io/blog/2024/otel-errors/ -> Concept page about “What are errors/exceptions”
• https://opentelemetry.io/blog/2024/scaling-collectors/ -> the ansible module would need to be donated to the community (which we asked for), then this could easily live under collector docs
• https://opentelemetry.io/blog/2024/getting-started-with-otelsql/ -> interesting one, would be great for Go > Libraries, but unfortunately the instrumentation library is not “official”
• https://opentelemetry.io/blog/2024/otel-collector-anti-patterns/ -> collector docs
• https://opentelemetry.io/blog/2023/any-metric-receiver/ -> collector docs
• https://opentelemetry.io/blog/2023/logs-collection/ -> great point in time article, but now python should have a proper documentation of logs
• https://opentelemetry.io/blog/2023/otel-arrow/ -> collector docs
• https://opentelemetry.io/blog/2023/synthetic-testing/ -> collector docs
• https://opentelemetry.io/blog/2023/k8s-runtime-observability/ --> this is an interesting one, since it provides insights into k8s built-in capabilities

For those that are more point-in-time, can we add tags to the blog posts so that they’re at least easier to find?

We had a similar ask in the past already ( I think for some of the end-user discussion blog posts ). Hugo has the tooling for it (see https://gohugo.io/content-management/taxonomies/), but as of today we have not made use of it, actually we have actively disabled it. This would be a separate issue to look into.

It would be nice to see a compilation of OTel tutorials on opentelemetry.io that are easy for folks new (and not so new) to OpenTelemetry to easily access.

Back on topic: Would you be able to provide a list of topics (outside of the blog posts that exist already) that would fit into that description? What tutorials would you like to see or what tutorials have you seen people asking for?

[avillela]

Looking through the OTel site right now, I think it's awesome that there is now a menu item under each lanuage to language-specific examples; however, it would also be nice to ALSO aggregate those under an "examples/tutorails" main section in the docs. I think the same can be done for:

• OTel Demo
• Collector
• Target Allocator

That way, it feels like a little less of an archeological dig.

Another thing which may be useful would be a section of "community examples" pointing to community blog posts and tutorials. @mhausenblas does such a great job with his newsletter to aggregate relevant community OTel content, and that could be a good place to start to get some of that info. But also put in a word of caution that this info can get stale very quickly as OTel evolves.

And finally, from talking to some folks, and even seeing some of the results in the "getting started" survey that we wrapped up last month (survey results coming soon), some folks seem to crave more complex examples of the OTel Collector.

Just some food for thought. I recognize that maintaining some of these things may be challenging, so perhaps we can start with the things that seem a bit more doable?

Happy to hear everyone's thoughts!!

[ricardoamaro]

I believe that we could start small, but with a good discussed framework based on the collective feedback in mind.
Taking the feedback from the community and focusing on improving the initial structure, accessibility, and relevance for OTel documentation. I also see advantages in both blogs and tutorials. We probably should pick a balanced mix that better serves the community from the start.

My opinion is that, while acknowledging the challenges of maintaining the content and the necessity for community involvement. It appears feasible to provide tutorials (or how-tos) for enduring documentation that we are confident will last for multiple minor versions, and possibly a few major versions. While this structure should default to blog posts since those would be more dynamic and time specific. Then organizing those with Hugo taxonomies seems like a good way of mix matching topics from several of the blogs.
So not everything would necessarily be a blog, but most of the content would. This, in fact, created more relevant content and drives more visitors.