[Docs]: Improve clarity and developer experience of the Collector quick start page

[favxlaw]

What needs to be changed?

I went through the Collector quick start page as a first-time user and identified several usability issues that may affect developer experience:

1. The "less than five minutes" time estimate doesn't account for installing Go, configuring GOBIN, or pulling the Docker image for the first time. This can affect user confidence early on.

2. Prerequisites list Docker, Go, and GOBIN without explaining which step depends on which tool, making it harder for readers to understand their relevance upfront.

3. Port 55679 and ZPages appear in the docker run command without explanation. The purpose of ZPages isn't clarified until later, making the command feel like boilerplate.

4. The Collector version (0.149.0) is pinned but there's no link to the releases page for readers to verify if it's current.

5. The optional grep command appears inline with the main steps, making it unclear whether it's required. This adds unnecessary complexity for beginners.

6. Next steps include advanced topics like building a custom Collector with OCB, which is not appropriate for someone who just completed a quick start. A more guided progression would help.

I have proposed improvements for each of these issues and am happy to submit a PR if the changes are welcome.

Name + path of the page

Collector Quick Start — content/en/docs/collector/quick-start.md

Additional context

I have already drafted improved versions of each section addressing these issues.
The rewrite is available as a documentation audit on my portfolio:
https://favxlaw.github.io/docs-audit.html

Happy to submit a PR with the proposed changes if maintainers are open to it.

[vitorvasc]

Hi @favxlaw, thanks for creating the issue! I appreciate the level of detail in your feedback.

@tiffany76, I believe this page was part of the Collector docs refactor efforts, are there any further changes planned for this content?

@open-telemetry/collector-approvers, PTAL.

[jade-guiton-dd]

This feedback seems reasonable to me.

For point 5: I'm not sure I'd call that step any more optional than the rest; overall, the Quick start page seems to be a very manual demo showcasing various OTel components, but it isn't representative of how people use OTel in practice at all. Maybe the fundamental problem is that this isn't made clear, and that newcomers reading "you are going to learn how to run the Collector and send data to it" will expect something somewhat production-relevant rather than a toy setup for introducing the Collector.

[favxlaw]

Thanks for this, that’s a really helpful reframing.

I agree that the issues I pointed out are likely symptoms of a deeper problem around expectation-setting. As a first-time reader, I approached the page assuming it was a production-relevant entry point, and there isn’t much early on that signals it’s more of an introductory/demo-style setup.

Something as simple as a short framing note near the top e.g. clarifying that this is an introductory walkthrough to demonstrate how the Collector receives and processes data, rather than a production setup, would already make the rest of the steps feel more intentional.

Would it make sense to start with that kind of change in a PR, alongside the other clarity improvements I outlined in the issue?

[mx-psi]

@favxlaw This is a bit of an uncomfortable message to write but I want to give you a good contribution experience so I need to address this before we move forward. I ran your messages through https://gptzero.me which seems to be 100% confident that both of your messages here are AI-generated. These tools make mistakes and I can't know that for certain but I would like to kindly ask you to read https://github.com/open-telemetry/community/blob/main/policies/genai.md to understand our AI usage policy.

As the page I linked implies, if you are using an LLM to communicate, we would like to ask you to try avoid doing that when communicating with us. I think we would all love to hear directly from you: a lot of people in OpenTelemetry do this work on a volunteer basis or at the very least because they enjoy getting people to learn more about our community and contribute, and this is hindered if you do not communicate directly with us.

[favxlaw]

@mx-psi Thanks for pointing this out here, didn't know how I skipped that policy, I have read through it. I appreciate you saying this.

I did use Claude to help me clean up how I wrote the message, but the feedback itself came from me going through the page for a project I worked on.

I will make sure to stick writing things in my own words going forward.

I’m still interested in contributing if that’s okay.

[mx-psi]

@favxlaw

I did use Claude to help me clean up how I wrote the message, but the feedback itself came from me going through the page for a project I worked on.

That is reassuring to hear :)

I’m still interested in contributing if that’s okay.

Of course! I think you can start with a PR and we can continue discussing over there :)

[tiffany76]

Hi @favxlaw! We'd love to have you contribute, and as @mx-psi said, we love talking to humans. 😀

The quick start guide definitely needs some love, so please put a PR and we'll go from there.

[favxlaw]

Sure thing @tiffany76 will submit a PR 🙂
Thank you :)