4 ms·

we also explain it a bit on our website, https://opentelemetry.io https://opentelemetry.io

systemvoltage 6y ago
The fact that this is the top comment and most people are confused about what Open Telemetry is about should indicate that it is not clear. This is too often a mistake - not knowingly. It's like proof reading, I always think my writing is correct until someone else points out mistakes.
- austinlparker 6y ago
  Thanks for the feedback, I just opened a PR to add a link from the spec readme to our website to hopefully guide people to better information.
  - systemvoltage 6y ago
    I want to clarify about my comment and what I meant - when you're working on your own product for many months and years, it is hard to know what others don't know about the product. Similar to proof reading, your eyes just "gloss" over :) I didn't mean to patronize or say you made a mistake.
  - m12k 6y ago
    With so many people finding things via GitHub, I'd highly recommend also including a single paragraph at the top of the repo readme to explain what it is, rather than expect people to be curious enough to go digging for more info. E.g. you could use the explanation from the website: "OpenTelemetry provides a single set of APIs, libraries, agents, and collector services to capture distributed traces and metrics from your application. You can analyze them using Prometheus, Jaeger, and other observability tools."
    - faichai 6y ago
      Yeah, particularly for a developer oriented product. GitHub readme is essentially a landing page and should be treated the same way, not assuming any foreknowledge for the reader.
  - mikewarot 6y ago
    Before I stopped reading, there was an example of a button being pushed... but there was no actual trace of a button being pushed... just lots of words and descriptions, which killed it for me. I just want to see what I'm getting into, not a vocabulary or jargon lesson, at least at first. That would lead us to then wonder why it was done that way, etc... and drive interest.
watt 6y ago
why not just put a couple paragraphs on top of the readme to explain what it is, what does it do, and add this link, instead of posting in a forum where nobody will see it.

The fact that this is the top comment and most people are confused about what Open Telemetry is about should indicate that it is not clear. This is too often a mistake - not knowingly. It's like proof reading, I always think my writing is correct until someone else points out mistakes.

austinlparker 6y ago
Thanks for the feedback, I just opened a PR to add a link from the spec readme to our website to hopefully guide people to better information.
- systemvoltage 6y ago
  I want to clarify about my comment and what I meant - when you're working on your own product for many months and years, it is hard to know what others don't know about the product. Similar to proof reading, your eyes just "gloss" over :) I didn't mean to patronize or say you made a mistake.
- m12k 6y ago
  With so many people finding things via GitHub, I'd highly recommend also including a single paragraph at the top of the repo readme to explain what it is, rather than expect people to be curious enough to go digging for more info. E.g. you could use the explanation from the website: "OpenTelemetry provides a single set of APIs, libraries, agents, and collector services to capture distributed traces and metrics from your application. You can analyze them using Prometheus, Jaeger, and other observability tools."
  - faichai 6y ago
    Yeah, particularly for a developer oriented product. GitHub readme is essentially a landing page and should be treated the same way, not assuming any foreknowledge for the reader.
- mikewarot 6y ago
  Before I stopped reading, there was an example of a button being pushed... but there was no actual trace of a button being pushed... just lots of words and descriptions, which killed it for me. I just want to see what I'm getting into, not a vocabulary or jargon lesson, at least at first. That would lead us to then wonder why it was done that way, etc... and drive interest.

watt 6y ago

why not just put a couple paragraphs on top of the readme to explain what it is, what does it do, and add this link, instead of posting in a forum where nobody will see it.