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?

[svrnm]

Apologies for not coming back to this earlier, I was occupied with a lot of other things, also localization;-)

I have still mixed feelings, and to be honest, I am also a little bit confused on what to do next: over the last few years we tried to make the docs more "tutorialesque" (to make up a word) by following pythons example to have a dedicated app (roll the dice) and follow this app as a tutorial through all the documentation. This is heavily work in progress and the main piece we are lacking is people that take the time and effort to write those docs. One part of this discussion was also to expand the operator docs with a getting started tutorial that builds on top of that (see https://github.com/pavolloffay/kubecon-eu-2023-opentelemetry-kubernetes-tutorial), but we need someone to handle that. Same is true for the Target Allocator. We have a page talking about it (https://opentelemetry.io/docs/kubernetes/operator/target-allocator/) but it's fairly basic and I have no issue with turning this into a full-detailed "tutorial" at exactly that place. And, for the collector as well we have some deep-dive pags as well and I would see a lot of value in making them more like a tutorial, e.g. Transforming Telemetry could have a section that helps people to have an environment available to test the things they are going to do throughout the document.

I am all for self-contained tutorial-like documentation, and if we find out that those tutorials need their own section, then let's have it, but for the more doable, more incremental changes I suggest we take a look at the things we have already and make them better.

Independent on that, and based on an idea by @jpkrohling we can provide a different view into our documentation, similar to https://kodekloud.com/learning-path/devops/ building on top of https://opentelemetry.io/docs/getting-started/ -- Same is true for an "examples" grouping at a higher level, we can make experiments with that and see how it works/fits into our existing logic.

Another thing which may be useful would be a section of "community examples" pointing to community blog posts and tutorials.

Some related discussions to that:

• Mention OTel recipes in "Ecosystem" page #4417
• Add 'examples' as a category into the registry #814

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.

My big issue with blog posts was and is that they require a significant amount of effort on reviewer site, while their value is often temporary. We have great tutorials in blog post form, I enjoy reading them, they are a great vehicle to drive visitors, but they take away bandwidth from maintainers I would like to see spend otherwise, that's also why we significantly raised the bar for blog posts (see here).

I anticipate, that from a contributor perspective a blog post is the easier thing to do, it is 100% self-contained, so you don't have to integrate into existing docs, it does not require continued maintenance and on top of that you get credit for it because your name is listed on the page and you can share it with your social networks.

[avillela]

I definitely agree with the new direction of prioritizing docs content over blog posts, as it will hopefully drive more folks to create more docs content. Even though docs are more "anonymous", PRs are not. So in much the same way that folks would share their blog posts on socials, I wonder how we can encourage folks to share their docs PRs on socials?

Also, I LOVE the idea of a learning path. That would certainly be helpful to a number of the folks who land on the site. I'm also hoping that we can gather further insights by running a docs survey. Related issue: open-telemetry/sig-end-user#33

[svrnm]

I wonder how we can encourage folks to share their docs PRs on socials

They could just share their contributions the same way they share their blog posts. Of course we could mention names of contributors on doc pages as well but for some of those pages the list would get really long really quickly and we would need to figure out a way how to order/highlight them.

Otherwise this is a question for the not yet formed contributor experience SIG how we can appreciate such kind of contributions

Also, I LOVE the idea of a learning path.

Yes, we could do better here, happy to take input on that.

[avillela]

Maybe we can do a quarterly blog post on the OTel blog with a shoutout to recent contributors and their contributors. This could be a good way to drive folks to the docs. A kind of, "Hey, look! The docs page for blah has been updated by Person X. Check it out!"

[jpkrohling]

I'm leaving another example here that left a good impression on me: https://nextjs.org/learn

[svrnm]

Following up on this discussion. I spend some time thinking about this and how we can improve the experience for end users to get started with OpenTelemetry, especially since we consider removing the "based on your role getting started", or at least replace it with something better (see @cartermp's comment here: #5155 (comment))

Reviewing @jpkrohling's other examples (Next.JS and Kodekloud, see above, as well as Rabbit.MQ), here is a proposal:

• We "remove" the "Getting Started" from all languages. The language api&sdk docs will move towards what we have proposed in Refactor java SDK and configuration #4966, there focus will be being aligned with the spec and being as detailed as possible (i.e. it often lists all the options you have for exporters, samplers, etc)
• We introduce a "Tutorials", "Getting Started" or "Learn" section that provides an end-to-end learning journey for ALL languages + collector + visualization. It's going to be highly opinionated, i.e. data is only exported via console/OTLP, no zero-code solutions are used, they are only mentioned and can have their own "Getting Started", etc.
• The code for this journey is managed via code-excerpts, i.e. language SIGs are maintaining them and making sure that they work. The structure is predefined such that importing them always works
• Below that "core tutorial" we allow custom tutorials, who are treated like "docs-contrib", meaning whoever contributes them will be code-owner for them and responsible to maintain them.
• Within the "core tutorial" we allow the addition of some "contrib" for visualizations, to address Visualizations we support in the documentation #5040

A thing we need to decide, is if we keep that within "Docs", or if we add a "Learn" or "Getting Started" area in the top corner of the page (see rabbitmq and Next.js)

or if we keep the "Getting Started" within Docs and put the content there (similar to https://kubernetes.io/docs/setup/)

[theletterf]

I like this proposal. It'd provide more meaningful startup guides and examples. My only suggestion would be to turn the existing getting started sections into the first of the new guides, even if they're library or product agnostic.

[svrnm]

An advanced proposal: https://docs.google.com/document/d/10HD5cdmKWza6GdS4Jdea3T74kqfXaVaaOwZ1juzFk5s/edit

[chalin]

Thanks for thinking this through and sharing proposals. Short answer to your last question: I'd keep it under Docs, and have a CTA button on the home page.