Restructure Language SDK & API documentation information architecture

[jack-berg]

Hi comms folks - at last week’s java SIG I raised a topic about possible improvements to the otel java documentation on opentelemetry.io. When I took a close look at the pages and their contents, I found a variety of consistency / vocabulary / coherence issues which may be making it harder for users to find answers than it ought to be. We discussed that a few of us from the java SIG could come to a comms SIG meeting to talk about this synchronously, and I plan to. But in the mean time, I’ve put together a document detailing some of the issues I’ve noticed an a proposal for my idealized organization: https://docs.google.com/document/d/1f761dYCNFTPJpAbLJAdmMFhwr9uy1j9gSrEmPdqnmHw/edit

Looking to start a conversation and see if my sentiments are shared by shared by others.

[svrnm]

As discussed during the last SIG meeting, I like the structure proposed in @jack-berg's google doc for a variety of reasons:

• it aligns the documentation with the structure of the Spec
• by that it communicates much better what we (OTel Community) care about, it is better aligned with our vision&mission
• it solves some issues we currently have with the existing information architecture (duplications, content that belongs together at different places, API&SDK intermix, etc.)

My only issue with the structure is that for a person not involved in OpenTelemetry (or observability) the structure will not help them to navigate, since they might know what an API & SDK are, but not know immediately what the difference is. Also the word "instrumentation" is something we assume people to know (already in todays doc), so for a 0 to 1 this navigation is hard to navigate. Note, that one of my assumptions is that people read no concept pages and want to dive into the matter directly, so we need to address this as good as possible.

Here is the structure proposed in the Google Doc above:

• Language APIs & SDKs
  • Java
    • Getting Started
    • Introduction
    • API
      • API usage
      • Instrumentation API
      • Native instrumentation guide
      • Semantic conventions
    • SDK
      • SDK core concepts
      • SDK autoconfigure
    • Instrumentation
    • Other resources
      • Registry
      • Examples
      • Javadoc
• Zero-code instrumentation

Here is a first iteration of it, trying to solve that problem outlined above:

• Languages
  • Java
    • Get Started by Example (make clear that this is a predefined app and that the goal is to get somewhere quickly)
    • Learn the Basics (the "introduction/overview" that re-iterates concepts, links to it's, calls out java specifics)
    • Capture Telemetry with the API (the API is all about adding (noop) signals like traces, metrics, etc. a "to your code", might be missing, an alternative: "Make your code observable"?, the "with the API" highlights that this is going into details with the otel api)
      • Use the API
      • Instrumentation API (@jack-berg you write "discuss instrumentation api abstraction", I am not 100% sure if I understand, can you provide me some more details what this is about?)
      • Add Telemetry for Library Developers (trying to make the task clear, end users might not know what "native" means)
      • Propagate context (this was missing, not sure where to include it, so I put it here)
      • Enrich telemetry with semantic attributes
    • Manage Telemetry with the SDK(same as above, the SDK is focused around the management of the telemetry that the API is providing, using "SDK" to highlight that this is the SDK section)
      • Use the SDK (Implementation of the API, Resources, ...)
      • Handling telemetry data (all the words about exporters, processors, samplers, etc.)
      • Configure the SDK (in the case of Java: auto-configure, can also be different for other languages)
    • Instrument an application (or "your" application, still uses the word "instrument", could also be "get telemetry from an application", section about instrumentation libraries, native instrumentation (as user) and Java Agent + Spring Boot Starter
    • Learn more
      • Performance
      • Examples
      • JavaDoc
    • Registry

[svrnm]

OpenTelemetry Java has something called the "instrumentation api", [...]
We might consider combining this into the "Use the API" section, since its essentially just using the API at a higher level of abstraction.

Thanks for the clarification. This seems to be a common pattern (and might get even more by the Sig Developer Experience), that there is the spec prescribed API, and then a language-specific higher level abstraction to make it easier to use. I think the auto configure is also similar to that, right? There is a "low level way of configuration", but we recommend that.

Having them combined is probably the best we can do for a start, later we can review things again and make a different decision if it feels better to have them at different places.

Add Telemetry for Library Developers (trying to make the task clear, end users might not know what "native" means)

Something like "Guide for library authors" might make this even more clear?

+1, I tried to use task-based titles ("Verb subject..."), but we can pick better titles if available.

Propagate context (this was missing, not sure where to include it, so I put it here)

That might be nested under API, but its an important enough concept that maybe it deserves its own page.

It's important in the sense, that people wonder about it and we have to tell them somewhere, "do not worry, we got you", so yes, maybe in "Use the API", but let's keep it as an option to have it separate.

Enrich telemetry with semantic attributes

Hmm.. enriching implies that this is some sort of user configuration option. Like, the collector can optionally enrich telemetry with additional contextual information from the environment. I think we want this pages title to convey something like "Produce standardized telemetry with semantic conventions". Now how to make that more concise? Maybe "Standardize with semantic conventions"?

Good point, "Standardize with Semantic Conventions" sounds good to me.

Use the SDK

Not sure its worth splitting "SDK core concepts" into pages for "Use the SDK" and "Handling telemetry data", since there's a lot of overlap.

Historically we didn't put a lot of content in parent pages, but we might want to change that, such that "Manage Telemetry with the SDK" holds a lot of content already, and we skip subpages if they would be to sparse.

Configure the SDK (in the case of Java: auto-configure, can also be different for other languages)

Maybe we could rename "Configure the SDK" to something like "Zero code SDK config" to differentiate with the content on "Use the SDK" and "Handling telemetry data".

+1

Instrument an application

I wonder what the best ordering is for these sections? If we expect most users to use off the shelf instrumentation, then it feels weird to have this page be so far down, which implies lower priority. But all users need to understand the basics of the SDK, and its useful to understand the SDK as an implementation of the API. So maybe the current order is necessary and reflects the natural order concepts need to be introduced.

Thinking about it, this page indeed needs to be way up, it's more of an overview page, it's a "When to use what" page, it should educate people around the options they have, depending on their use case (i.e. it points to the guide for library authors, it points to the agent for people looking for zero code, it points to the SDK for people that want code-based instrumentation), etc.

[cartermp]

Some drive-by commentary:

Learn the Basics (the "introduction/overview" that re-iterates concepts, links to it's, calls out java specifics)

I would propose that this be a more "practical" overview of concepts rather than a re-iteration of what we already have in the conceptual section of the docs. Those already cover in much more detail the different signal types and what they're used for.

Instead, I'd prefer that Java lead the way here in describing less the concepts, and more how the agent/sdk are designed to capture and connect all the useful signals from your application. For example, less a re-iteration of what traces/metrics/logs are, and more a description of what you get by installing the agent and what you get by loading up an SDK and instrumenting your application. Does that make sense? There's plenty of opportunities in something like that to link out to the concepts that are language-agnostic.

Thinking about it, this page indeed needs to be way up, it's more of an overview page, it's a "When to use what" page

Agreed, this should probably be the third item in the TOC. By my estimation, the large majority of people who come to these docs are looking for straightforward guidance on what to use and how to use it, followed by application devs who have a very specific need (e.g., "I need to know how to use span links"), followed by a longer tail of people providing native instrumentation, customizing their company's SDKs in some way, or some other more advanced usage.

[jack-berg]

Instead, I'd prefer that Java lead the way here in describing less the concepts, and more how the agent/sdk are designed to capture and connect all the useful signals from your application. For example, less a re-iteration of what traces/metrics/logs are, and more a description of what you get by installing the agent and what you get by loading up an SDK and instrumenting your application. Does that make sense?

I think so. In my head, we need a page that links orients the user to the vocabulary with links out to the language-agnostic pages with detailed definitions, and tells the user how those concepts are embodied in the java language and route users to the appropriate pages for more info. I think of it primarily as a routing page: its the entry point of the funnel for users with just enough info on each topic to connect the dots for a reader's mental picture, but quickly re-route them to the more appropriate / complete page.

By my estimation, the large majority of people who come to these docs are looking for straightforward guidance on what to use and how to use it, followed by application devs who have a very specific need (e.g., "I need to know how to use span links"), followed by a longer tail of people providing native instrumentation, customizing their company's SDKs in some way, or some other more advanced usage.

👍 I agree.

[jack-berg]

This discussion is getting a bit long and I think its time to summarize to make it more consumable.

• At a high level, we want to rework the docs language implementation info hierarchy (i.e. navigation) to improve the reader experience, which means getting them to the right place more quickly and more intuitively.
• More descriptive page titles: Current page titles are subject to misinterpretation: Is "Instrumentation" a page describing how to instrument with the API or the set of off the shelf tools for instrumenting or something else? Is "Getting started" an intro to the language's ecosystem or a sample app? Let's move away from one word page titles to concise multi word titles which are harder to misinterpret. For example, "Capture telemetry with the API" for a page describing how to use the API. The "capture telemetry with.." is consumable for newcomers, while the inclusion of "API" is immediately obvious to folks familiar with OpenTelemetry and introduces newcomers to our vocabulary.
• Mirror specification distinction of API and SDK: The current info architecture largely ignores the key concept of the difference between API for capturing telemetry and a separate SDK implementation for managing that telemetry. Treating API and SDK as first class concepts in the docs more quickly introduces readers to the OpenTelemetry architecture, and makes it simpler to write and maintain docs as the organization better reflects reality.
  • Collocate SDK content: The current info architecture scatters SDK information across a number of pages (Exporters, Resources, Samplers, Instrumentation, and Getting Started). Let's bring that content together, making it clear that the SDK is the user configurable / extensible reference implementation of the API. This means a new page (or section) called "Manage telemetry with the SDK"
  • Collocate API content: The current info architecture scatters API usage information across Getting Started and Instrumentation. Let's bring that content together into a page (or section) called "Capture telemetry with the API". Let's also make it clear that the API is meant to be a dependency for libraries and frameworks adopting native instrumentation, and for end users looking to add additional custom / manual instrumentation to their app. Let's also make it clear that we have semantic conventions for standardizing instrumentation and generated constants to help use them which should be used when applicable.
• Prioritize page describing instrumentation landscape: Most readers just want to install instrumentation on their app. But the instrumentation landscape is complex, with zero code instrumentation, library instrumentation, native instrumentation, and custom instrumentation options. Let's reflect this common case in the navigation and introduce a page near the top of the navigation which explains the instrumentation landscape for the language, and list the tools available and route users to any additional docs for each category of instrumentation.
• Group and deprioritize other pages: The current info architecture places things like "Javadoc", "Examples", "Registry, and "Performance" as siblings at the same level of priority as the API, SDK, and Instrumetnation. Let's group these together in a section named "Learn more" that clearly communicates that they are supplementary to the more core pages.

[svrnm]

Thanks for the summary @jack-berg, I think we can move forward with #4966, as a next step I would suggest we see if another language want's to adopt that change as well allowing us to extract common content and see how easy it is to use it across languages.

@open-telemetry/cpp-approvers @open-telemetry/go-approvers @open-telemetry/dotnet-approvers @open-telemetry/erlang-approvers @open-telemetry/javascript-approvers @open-telemetry/php-approvers @open-telemetry/python-approvers @open-telemetry/ruby-approvers @open-telemetry/rust-approvers @open-telemetry/swift-approvers