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

[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

[hdost]

Looks great, love the newly proposed formatting 👍🏼