Omnibus Documentation Consolidation 2k22

[austinlparker]

Preface

OpenTelemetry suffers from a lack of authoritative content. This is due to several factors, most of which aren't terribly interesting or relevant to this issue, but it is an issue we are resolving to fix. In the absence of authoritative, centralized, educational content about the project many alternate sources have popped up on vendor blogs or documentation pages. The OpenTelemetry Communications SIG wishes to ameliorate this by making https://opentelemetry.io the authoritative source for project information and documentation.

Goal

We propose to consolidate the vendor-neutral OpenTelemetry content (both conceptual and instructional) from vendor blogs and documentation sites into opentelemetry.io. This content would be reviewed, annotated, and merged with other existing documents in order to align with the desired information architecture and published on opentelemetry.io. Vendor-specific information would be stripped out as needed -- this includes references to vendor distributions of the SDK or Collector, specific configuration information for a vendor, or features that only work with a specific vendor.

After this process has completed, we encourage vendors to point their documentation pages for OpenTelemetry to this new resource and only publish vendor-specific addendum to their documentation pages. We will work with vendors to ensure that the documentation and conceptual information is structured in such a way as to have clear annotation points for vendors to utilize (i.e., around configuration, event management, attributes, etc.) in their addenda.

Existing Content

This is a list of existing content that we would see migrated.

• Lightstep: Link
• Uptrace: Link
• Honeycomb: Link
• Splunk: Link
• Aspecto: Link
• New Relic: Link

Open Questions

• How do we get buy-in/approval for this from owners of existing content?
• How should we handle the consolidation?
  • Option 1: Migrate existing content into the existing tree, then merge it with existing IA
  • Option 2: Leave existing content as-is, evaluate it in-place and then take various parts into existing IA
  • Option 3: Pick one existing content source and use that as the 'new' base, then consolidate against that.
  • Option 4: ???
• When is the consolidated content 'done' enough for vendors to redirect their users towards it?

[cartermp]

Some others:

https://opentelemetry.uptrace.dev/
https://docs.honeycomb.io/getting-data-in/opentelemetry-overview/ (may have more conceptual content soon-ish)
https://www.splunk.com/en_us/data-insider/what-is-opentelemetry.html
https://www.aspecto.io/blog/what-is-opentelemetry-the-infinitive-guide/

[sharrmander]

@austinlparker Here's New Relic's OpenTelemetry masterclass content for review/consolidation consideration too.

[svrnm]

Based on the discussion on twitter, I'd like to share an idea we discussed internally a while back, that might be beneficial for vendors & the oss community, and make it easier for everybody to collaborate. Let me know if this is part of this issue or if I should open a new one.

Problem

When customers buy an observability solution that supports opentelemety from a vendor they expect the vendor to give them good documentation, tutorial & troubleshooting for setting things up, running & maintaining them. From a vendor perspective the best thing for the customer is a single place where everything is stitched together:

Example: if the customer wants to instrument apps & setup a collector, the vendor can give them a single place to get started. They also can put some pointers on that page where to find help:

Now, this duplicates a lot of work that should flow towards the community to make the OSS part of the documentation great.

The alternative right now is to point out from the vendor documentation to the OSS documentation. The issue here is of course, that the customer is send off from vendor to community documentation`, without having a "pointer back" and also some details there that might be "too much information":

From a vendor perspective it might appear easier to write your own stuff vs pointing out and contributing to open community documentations.

Solution

I don't think this solution is new, probably someone already has some experience with it, I just wanted to put it out for discussion, is this something that could work with the otel documentation:

like the code the documentation is open source (licensed CC-BY), so what a vendor could do is making a "distribution" of it:

Open questions

While it makes it easier for a vendor to contribute back to the OSS documentation, since they can make use of it like they do with code, there are a few implications which make this difficult to use (and maybe impractical overall):

• legal obligations: vendor takes liability for the content (e.g. someone adds malicous code into an example and it is redistributed to the vendor, etc.)
• deviations: if a vendor provides a change that's important to them to the documentation, but it's not accepted by the community, they might start to deviate and have a hard fork from the docs.
• structure: of course the oss documentation would need some re-work to make it easy for a vendor to mix content with their own (e.g. where to put pointers back in the docu, or maybe where can snippets be replaced, etc.)
• ...

Let me know what you think

cc: @austinlparker, @chalin, @lizthegrey, @alolita

[cartermp]

Hmmm. So I think I actually disagree with this:

From a vendor perspective the best thing for the customer is a single place where everything is stitched together:

In Honeycomb's case, we've consistently had customers and prospects complain that they googled about OpenTelemetry and didn't find what they wanted in the actual OpenTelemetry docs. They did not expect us to be the ones who documented all OpenTelemetry concepts. They expected us to document how you get ensure OpenTelemetry data can be sent to Honeycomb. And several were quite frustrated that it was other vendors who had more information, and that this information was also incomplete (but in a different way), causing them to hop around to multiple sites.

However, I like the general approach where there's a list of known vendors that we can simply link out to. Have generic docs for sending to an endpoint/collector, then have somewhere people can click that lists known vendors who will accept OTLP data. The AWS ADOT docs actually do this (and go a step further by documenting some basic information), but I wouldn't say that's necessary.

[cartermp]

Another one: https://logz.io/learn/opentelemetry-guide/