[Meta] Add TypeScript to JavaScript documentation

[svrnm]

What needs to be changed?

As discussed in #1769 we want to have typescript code snippets alongside the javascript one. We want to use tabbing like the elixir/erlang documentation is doing it right now, (e.g. here):

{{< ot-tabs TypeScript JavaScript >}}
{{< ot-tab >}}
/* TS Code */
{{< /ot-tab >}}
{{< ot-tab >}}
/* JS Code */
{{< /ot-tab >}}
{{< /ot-tabs >}}

TypeScript should be the default.

(Edit by @chalin) Consider using Docsy's tabbed panes, if they work for you:

{{< tabpane >}}
{{< tab header="TypeScript" lang="ts" >}}
/* TS Code */
{{< /tab >}}
{{< tab header="JavaScript" lang="js"  >}}
/* JS Code */
{{< /tab >}}
{{< /tabpane >}}

What is the name + path of the page that needs changed?

• [x] #1799, @kaiwalyakoparkar
• [x] https://github.com/open-telemetry/opentelemetry.io/pull/1834
• [x] https://opentelemetry.io/docs/instrumentation/js/instrumentation/
• [x] https://opentelemetry.io/docs/instrumentation/js/exporters/
• [ ] https://opentelemetry.io/docs/instrumentation/js/resources/
• [x] https://opentelemetry.io/docs/instrumentation/js/getting-started/browser/
• [ ] https://opentelemetry.io/docs/instrumentation/js/api/context/
• [ ] https://opentelemetry.io/docs/instrumentation/js/api/tracing/

Additional context

We need help to get this accomplished, if you like to help, pick one page and let us now, so we can assign it to you!

cc: @open-telemetry/javascript-approvers , @open-telemetry/javascript-maintainers

[cartermp]

So one issue with this approach (the tabs thingie) is that some tooling for auto-formatting markdown line lengths don't recognize those tags. And so it can make the docs get fucky. I'll have to experiment with alternatives to rewrap to see if this is still doable with another tool.

[svrnm]

So one issue with this approach (the tabs thingie) is that some tooling for auto-formatting markdown line lengths don't recognize those tags. And so it can make the docs get fucky. I'll have to experiment with alternatives to rewrap to see if this is still doable with another tool.

I was not aware of that, do we have issues with erlang/elixir as well, those docs make heavy use of the tabs already.

[cartermp]

Yep, I tried using it to format those docs and ran into the problem too.

[kaiwalyakoparkar]

Hey, I would like to work on the first page "getting started". Can you please assign it to me also can you help me with the essentials I should know etc

[svrnm]

@kaiwalyakoparkar, awesome! I'll raise a separate issue & assign it to to you, we will keep this one for tracking.

(Edit by @chalin) See the opening comment for the kind of tabbed panes you should use.

~Please have a look at the elixir docs, they use a tabbing mechanism already. You should be able to do something like the following through out the doc: ... The tabbing does language detection for you, so you should get that for free.~

Note what @cartermp said above, that the tabbing does not (yet) work well with auto-formatting so please pay attention on markdown issues and do not try to fix them automatically.

[amanksdotdev]

Hey, I would like to work on the "libraries" page, can you please assign it to me? Going through the code in docs, I have a few doubts and it would be helpful if you can clear those

1 - For typescript code can we use ES6 imports or stick to CJS? (because ES6 imports will be able to infer types as well)

2 - Second doubt depends on the answer to the first one.

• If we can use ES6 imports, should I add explicit types on a variable or the inferred one is preferred?

  
  // inferred
  const provider = new NodeTracerProvider({
  resource: resource,
  });

// explicit const provider: NodeTracerProvider = new NodeTracerProvider({ resource: resource, });

-  if we cannot use ES6 imports then do I have to write types/interfaces for variables or let it default to `any`?

[cartermp]

@amanksingh99 You should be able to use imports for the typescript, yeah. If you follow the pattern in https://github.com/open-telemetry/opentelemetry.io/pull/1800/files then things should be pretty good. Thanks for offering to contribute!

Filed https://github.com/open-telemetry/opentelemetry.io/issues/1829 to track separately

[chalin]

Hi all. Since we've agreed to switch to Docy's tabbed panes, I've updated the comments in this issue to reflect that, in the opening comment in particular.

[amanksdotdev]

@chalin the docsy way of writing as you suggested gives me this error, what could be the possible reason?

[chalin]

@amanksingh99 - For that error, try rebasing your branch to pick up the latest Docsy. Let me know if that helped.

[chalin]

Hi all. Since we've agreed to switch to Docy's tabbed panes, I've updated the comments in this issue to reflect that, in the opening comment in particular.

I rolled that back since I hit a bug in the Docsy tabbed panes. I've re-edited the opening comment, which now again refers to the Erlang pages as an example. Note that the OTel shortcodes are now named ot-tabs and ot-tab. You can, of course, try the Docsy tabs, they do work in some cases. :)

Sorry for the confusion!