Docs on opentelemetry.io

[svrnm]

hey there,

we are currently reviewing what is still missing on the OpenTelemetry Docs over at opentelemetry.io, the C++ is empty and linking to readthedocs. I was wondering if we should have some Getting Started on the website as well or move/copy some of that content over?

TY

[lalitb]

We thought of keeping it in one place (i.e, readthedocs) for better maintainability. But we can do something similar to OpenTelemetry .Net - i.e maintain the links to actual documentation, instead of copying the stuff.

We can have links for -

Overview: https://opentelemetry-cpp.readthedocs.io/en/latest/api/Overview.html
Instrumenting code: https://opentelemetry-cpp.readthedocs.io/en/latest/api/GettingStarted.html
Configuring the SDK: https://opentelemetry-cpp.readthedocs.io/en/latest/sdk/GettingStarted.html#tracerprovider
Exporters: https://opentelemetry-cpp.readthedocs.io/en/latest/sdk/GettingStarted.html#exporter

Haven't done any PR to opentelemetry.io, if someone can help on that?

[svrnm]

Starting with updating those links is great, it gives people an easier way into it! I can take care of that.

There's this issue on having the docs at opentelemetry.io for "improving user experience and SEO", so I am trying to see where languages are standing today.

I understand that you want to avoid duplication and keep maintenance for the docs low, having different priorities and limited bandwidth for all the work that needs to be done.

So, let me ask that differently: is the readthedocs set for the c++ docs or would the SIG be open to migrate the content over (assuming that someone else is doing the heavy lifting)?

[lalitb]

So, let me ask that differently: is the readthedocs set for the c++ docs or would the SIG be open to migrate the content over (assuming that someone else is doing the heavy lifting)?

Just to clarify, we are only talking about non-API documentation. As API documentation uses doxygen -> breathe -> sphinx -> readthedocs to generate and push.

[svrnm]

So, let me ask that differently: is the readthedocs set for the c++ docs or would the SIG be open to migrate the content over (assuming that someone else is doing the heavy lifting)?

Just to clarify, we are only talking about non-API documentation. As API documentation uses doxygen -> breathe -> sphinx -> readthedocs to generate and push.

Yes. Exactly. I think python sig is also keeping api & sdk docs in read the docs.

[lalitb]

I don't see any issue in moving non-api docs to opentelemetry.io, but I am not the only one to decide :) Will discuss this in next week's SIG meeting to see if all the members agree. Will update the issue accordingly.

[svrnm]

Sure, thank you :-)

[marcalff]

To discuss in the SIG meeting.

@svrnm , @lalitb , some questions here:

I would like to understand the expected workflow, from a developer perspective.

opentelemetry-cpp is a repository, with issues, PR, reviewers, CI, and its own git history, release labels, etc
openteletry-io is another repository, likewise

From past experience in other organizations, having two separate flows, where a dev is asked to:

• push code in one repo
• push doc in another repo
  never works in practice, as things diverge very quickly, or do not happen at all.

Even when the reviewers are the same persons, the burden of maintaining these parallel paths consistent makes this impractical.

Can we have something like:

• opentelemetry-cpp as the source of truth, so a PR contains the code and the doc for a feature, reviewed together, tagged together with the same label when releasing a version,
• opentelemetry-io/content/en/docs/instrumentation/cpp as a mirror of that documentation.

How to synchronize in practice:

• manual sync
• manual sync every release
• automated sync from opentelemetry-cpp to opentelemetry-io
  can be further discussed and resolved, this should not be a major issue.

We can organize the docs source under opentelemetry-cpp with a specific folder for content to publish in opentelemetry-io, to make that sync simpler, if needed.

Regards,
-- Marc

[svrnm]

@marcalff To answer your question, yes using opentelemetry-cpp as source of truth is possible, there are currently two SIGs (go, ruby) that provide the documentation source via their project, see:

• https://github.com/open-telemetry/opentelemetry-go/tree/main/website_docs
• https://github.com/open-telemetry/opentelemetry-ruby/tree/main/website_docs

I know that some other SIG (python?) abandoned that eventually, let me see if I can track down the history, to see why they did it. And, while I agree with you that it has some upsides to keep the docs within a single source of truth, it also comes with a few downsides:

• Additional synchronisation is required as you called out, that's doable and we have a solution for ruby&go already
• For a PR created in opentlemetry-cpp you can not leverage the workflows of the docs out of the box (markdown validation, previews, etc.) and we (@open-telemetry/docs-approvers) are not notified out of the box to do some prove reading.
• People reading the docs can (and will) report issues to the opentelemetry.io repo, so we have to push them down to the cpp project as needed
• ...

At the end the workflow needs to serve the CPP SIG best. If you like I (or @cartermp) can join one of your SIG meetings to discuss.

cc: @open-telemetry/docs-approvers

[marcalff]

• People reading the docs can (and will) report issues to the opentelemetry.io repo, so we have to push them down to the cpp project as needed

Thanks @svrnm , this is an important point to consider.

We do not want to have:

• some changes done in -cpp, merged to -io
• other changes done in -io, merged to -cpp
  at the same time, I think we all agree on that.

Another point to consider, is that changes to the doc will most likely be:

• editorial in nature (styles, URL links, etc), to align with the general content of -io
• technical in nature (content of the doc itself), to align with the product behavior in -cpp

Doing editorial changes in the -cpp repository will be awkward and inconvenient as well, I assume.

Waiting for other people in the C++ SIG to comment, to find the best solution.

Regards,
-- Marc

[cartermp]

I know that some other SIG (python?) abandoned that eventually, let me see if I can track down the history, to see why they did it.

Mostly because we offered to take on the burden of maintenance and updating content. Which we did! And then we also revamped the exporters, manual instrumentation, and getting started pages too. Since then the Python folks have also added some more technical content, and are diligent with reviews. It's about as good as an arrangement as we can hope for 🙂.

My one caution is that my own C++ skills are from college, and so I'd need more time to ramp up on being able to write effective code samples compared to the likes of Python/Ruby/Go, etc. This would certainly be in the scope of my own maintainer's duty, but if there are subtleties in using the API/SDK that require more advanced knowledge of C++ (e.g,. this true for Go but not necessarily true for .NET) then I'd definitely need help and/or time.

[marcalff]

Doc team:
@svrnm
@cartermp
@open-telemetry/docs-maintainers

Cpp team:
@lalitb
@owent
@esigo
@ThomsonTan
@open-telemetry/cpp-maintainers

cc: @open-telemetry/docs-approvers
cc: @open-telemetry/cpp-approvers

We discussed documentation in C++ SIG meeting on 2022-09-07,
please see the proposal below, and comment.

Regards,
-- Marc

Desired state

Documentation content falls into several categories.

Some documentation is for the general public (users of otel-cpp),
for example a "GettingStarted" page.
Let's call this kind of doc USER-DOC.

Some documentation is for maintainers of opentelemetry-cpp,
for example existing docs/semantic-conventions.md.
Let's call this kind of doc MAINTAINER-DOC.

Some documentation is for the general public (users of otel-cpp),
and covers in details the exposed opentelemetry-cpp API,
for example the doxygen documentation generated from the source code.
Let's call this kind of doc API-DOC.

For USER-DOC, the content is maintained in the opentelemetry.io repository,
under a directory dedicated to cpp (content/en/docs/instrumentation/cpp),
in base language (en).

opentelemetry.io is the only source of truth for USER-DOC.
opentelemetry-cpp will contain no USER-DOC, and there will be no
sync mechanism between the two repositories.

In the long term, USER-DOC is to be translated, with each translation in a
different directory (for example, content/fr).

For MAINTAINER-DOC, the content is maintained in the opentelemetry-cpp
repository. opentelemetry.io will contain no MAINTAINER-DOC.

There are no plans to translate MAINTAINER-DOC, it will stay in base
language (en) only.

For API-DOC, the original content is maintained in the source code,
and therefore is maintained in the opentelemetry-cpp repository.
opentelemetry.io will contain no API-DOC in source format.

There are no plans to translate API-DOC, it will stay in base
language (en) only.

The USER-DOC in opentelemetry.io comply with the general rules
in place for opentelemetry.io, including:

• doc format
• general structure
• CI checks and tooling

The MAINTAINER-DOC in opentelemetry-cpp comply with the rules
and tooling in place in opentelemetry-cpp, including:

• doc format
• general structure
• CI checks and tooling

The API-DOC in opentelemetry-cpp comply with the rules
and tooling in place in opentelemetry-cpp, including:

• doc format
• general structure
• CI checks and tooling

There is a tooling chain to publish doxygen API-DOC already.

The main point here is that the choice of doc format, tools, processes,
etc are likely to be different for USER-DOC, MAINTAINER-DOC and API-DOC, and this is ok.

Migration path

Identify content that is considered USER-DOC that currently resides in opentelemetry-cpp

Define the desired doc format (.md ?) and source organization for USER-DOC in opentelemetry.io

Create a PR for opentelemetry.io to add migrated cpp USER-DOC.
In particular, change the file format (.rst to .md ?) if needed.

Create a PR for opentelemetry-cpp to remove migrated cpp USER-DOC.

Review existing issues in opentelemetry-cpp related to USER-DOC, if any,
and address them (close if already fixed, migrate issue to opentelemetry.io, or fix in opentelemetry.io)

Ongoing activities

Everyone is expected to:

• consider whether something belongs to USER-DOC, MAINTAINER-DOC or API-DOC,
  before creating new content.
• place content in the proper place (opentelemetry.io or opentelemetry-cpp),
  in the proper format,
  based on the type of content.
• follow per repository rules and processes.

Maintainers of opentelemetry-cpp are expected to:

• contribute USER-DOC content in opentelemetry.io
• review PR for USER-DOC changes in general,
  with a particular attention to the technical C++ details
  (feature descriptions, correctness of C++ code examples, ...)

Maintainers of opentelemetry.io are expected to:

• contribute USER-DOC content in opentelemetry.io
• review PR for USER-DOC changes in general,
  with a particular attention to the general doc structure
  (usage of tools, styles, layout, rendering, ...)

[lalitb]

Thanks, @marcalff for summarizing the discussion, this seems to cover all the aspects. Just to add, while the USER-DOC is stored/published in the opentelemetry.io, we can still maintain the links to it in readthedocs. This will require minimal maintenance from opentelemetry-cpp maintainers, but the readthedocs would look complete. otel-python already does something similar - https://opentelemetry-python.readthedocs.io/en/latest/.

[marcalff]

Each kind of documentation is not isolated from the rest, so sure, we can have links from one space to another.

[cartermp]

It's worth noting that the only docs there for python are API docs for various packages (and there's some examples for those APIs too). That's because we don't have a solution for API docs across OTel (and arguably shouldn't, since several languages have their own native way to represent API docs that are likely much more expected than if we built our own solution).

[yonatan555]

maybe beginners tutorial , step by step to incorporate open-telemetry into exist project

[svrnm]

@lalitb , @marcalff : how do we want to proceed? I could raise some issues over at github.com/opentelemetry.io for the content we already have for other languages / for the content you want to see:

• Getting Started
• Manual (Instrumentation)
• Exporters
• ...

[marcalff]

@lalitb , @marcalff : how do we want to proceed? I could raise some issues over at github.com/opentelemetry.io for the content we already have for other languages / for the content you want to see:

@svrnm , please raise issues in .io, and assign them to me. With the new fancy sig:cpp tag as well.

[lalitb]

@svrnm - Just curious how is the version mapping managed between SIG releases and it's documentation in opentelemetry.io, or if you know how other teams are handling it.

In readthedocs.io, users can navigate to docs specific to the release they are on. E.g - https://opentelemetry-cpp.readthedocs.io/en/v1.6.0/ for 1.6.0 release. Do we need to have sig-specific release tags in opentelemetry.io to manage it?

I understood from the last maintainers meeting that the docs team would come up with guidelines/process for publishing documents before we plan to migrate.

[svrnm]

@svrnm - Just curious how is the version mapping managed between SIG releases and it's documentation in opentelemetry.io, or if you know how other teams are handling it.

In readthedocs.io, users can navigate to docs specific to the release they are on. E.g - https://opentelemetry-cpp.readthedocs.io/en/v1.6.0/ for 1.6.0 release. Do we need to have sig-specific release tags in opentelemetry.io to manage it?

We discussed this a few times, but so far we decided to not have it and keep things at the latest version (and reduce our maintenance overhead significantly): Since the USERDOCS are geared towards new comers I think this should be ok for now. If we ever run into issues with that because of breaking changes we will re-evaluate

I understood from the last maintainers meeting that the docs team would come up with guidelines/process for publishing documents before we plan to migrate.

Yes, we will follow up with some more plans, cc: @cartermp

[svrnm]

@lalitb , @marcalff , following up on this:

I understood from the last maintainers meeting that the docs team would come up with guidelines/process for publishing documents before we plan to migrate.

Before I go down into details, let me put upfront, that the final decision on how&where things are documented for a specific SIG of course lays with the SIG, so all we can provide are guidelines/recommendations, and that the following is how it works best for the docs contributors:

• Our goal is to have a similar set of instructions geared towards end users:
  • A "getting started" that provides installation instructions and a quick&easy way for end-users to get a sample application instrumented
  • A page about "automatic instrumentation" (maybe not applicable for C++?)
  • A page about "manual instrumentation" (tracer/meter init, creating spans, set attributes, events, links, similar for metrics: Sketch out how metrics should be documented for each language SIG opentelemetry.io#1746 (comment))
  • A page about "exporters" (to stdout might be part of the getting started, some thing about OTLP, maybe jaeger,zipkin,prometheus, ...)
  • A page about "resources"
• We would raise an issue for each of these pages with the opentelemetry.io project and mark them as "sig:cpp" "help wanted" and "good first issue"
• We (the docs contributor) can take care of a lot of the writing, where we might need help from the you (C++ SIG) are the code snippets etc, so even if you don't feel comfortable with the writing part, we can start with something that's mostly code and only some hints what the text should look like
• We can also copy some of the writings from other language docs

Hope that makes sense, (cc: @cartermp, did I forget anything?)

[cartermp]

LGTM @svrnm.

I'd add that also, we're in a bit of a special time now with Metrics, where there's a lot more content that will need to be added soon, and we'll need to call upon SIG members to help with that. Once they're in, getting them into a steady state and keeping them up to date is relatively easy.

[svrnm]

• provides installation instructions and a quick&easy way for end-users to get a sample application instrumented

done

[github-actions]

This issue was marked as stale due to lack of activity.

[svrnm]

I think this can be closed, since the initial goal of this issues has been accomplished, @lalitb , @cartermp ?

[cartermp]

yep, agreed

[lalitb]

Yeah we can close it I guess. We have user docs in opentelemetry.io. API docs can remain in readthedocs as of now. Unless @marcalff has some other thoughts.