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, ...)