Suggestions for docs to work on

[tsloughter]

I'm opening this issue both to list some of my thoughts on needed docs and to solicit suggestions on what docs people would like to see. These apply both to the website's Erlang docs, https://github.com/open-telemetry/opentelemetry.io/tree/main/content/en/docs/instrumentation/erlang, and hex.pm docs, mainly focusing on the API https://hexdocs.pm/opentelemetry_api/readme.html and SDK https://hexdocs.pm/opentelemetry/readme.html

• set_status
  • [ ] API docs
  • [ ] website example
• [ ] samplers: website example

I'll keep adding as I find more.

[albertored]

I think a big step forward would be to define a list of modules/functions that we want to be exposed to users, add a description to all of them and hide from hex.pm all other internal functions since at the moment all modules/functions are exposed and mostly of them are without any description.

[tsloughter]

Agreed.

[whatyouhide]

I’m picking this back up as I think right now it's the biggest issue with opentelemetry-erlang docs: it's really hard to figure out what's the API that end users are supposed to use.

So, for Erlang in opentelemetry_api, I think what we want to be public is:

• opentelemetry
• otel_attributes
• otel_baggage
• otel_ctx
• otel_span
• otel_tracer

What about the otel_propagator* ones? Or otel_tracer_noop/otel_tracer_provider? I don't want to go too deep into this... small steps 🙃

[tsloughter]

I think all propagator ones need to be shown. It is a little awkward since only otel_propagator_text_map is to be called but the others give you the name of the module to use when configuring which propagator to use.

The tracer provider should be public too. We just need better docs around what it is and how to (rarely) use it bc it is used indirectly in our case. Technically you get a Tracer from calling TracerProvider and then use that Tracer to start a span, but we macro around that for the common case of wanting a Tracer from the global Provider named for the current Application.

otel_tracer_noop shouldn't be called by the user but may be used in configuration, so that is a tossup.

[whatyouhide]

@tsloughter good call. We can easily show all the propagator modules and otel_tracer_noop, just hide all the functions in them, so that it's clear that users are not meant to call them?

[tsloughter]

Sounds good.