Write complete persona-specific "how to use this" docs

[ktoso]

We should stick to our "division" of "who" and "how" uses this API and fully document it. Only once fully documented and proven in one or two integrations can we slowly claim to stabilize the API.

Complete documentation has a magical power of uncovering edge cases etc, and of course matters for adoption.

Our "personas" are:

• end users
  • "pass around context" instrumented libs do the right thing
  • you can get a tracer and start spans yourself
• library and framework authors / "system authors"
  • this is where and how to pass context
  • this is how you can start spans on behalf of users
• instrumentation developers
  • this is how to develop an instrument
  • this is how to develop a tracer and span

[slashmo]

Forgot to close this via #139. @ktoso feel free to re-open if not everything has been covered yet.

[ktoso]

Sounds good thanks :) so far we're okey, will revisit in some time