Documentation: Getting started guide and examples overlap

[mauriciovasquezbernal]

From #544 (comment).

There is a lot of overlapping information in the getting started guide and the examples, some of the examples are almost identical in both places making if difficult to maintain and giving no value for the user.

The following table tries to summarize the duplicated logic:

Getting Started	Examples
Hello world	Basic tracer
Jaeger Exporter	Jaeger Exporter
Flask Integration	http integration
metrics	basic meter *
prometheus	prometheus
ot collector	ot collector metrics & ot collector tracer

*: the basic meter examples covers the usage of the batch calling convention as the observer instrument.

The only things that are not covered in the getting started guide are the example app and autoinstrumentation.

My proposal would be to get rid of the duplicated examples, keeping only the ones that provides added value (like usage of observer instrument and batch calling convention, also autoinstrumentation).

As an implementation detail, I think it is a good idea to move all the embedded code to proper files and transclude them in the documents, so people that have the source code available don't have to copy & paste all of them.

/cc @toumorokoshi

[toumorokoshi]

Sounds good! your approach is spot on IMO.

Regarding the duplicated examples: it seems like it would be best just to inline the code from the samples into the getting started guide. Thoughts on that? There will probably a little bit of work on the existing samples to ensure consistency in patterns like instantiating the SDK.

The only things that are not covered in the getting started guide are the example app and autoinstrumentation.

Should they be? I guess the example app might be redundant if we have more granular examples. Although the example app has a test suite, and I don't believe the samples do.

[mauriciovasquezbernal]

Regarding the duplicated examples: it seems like it would be best just to inline the code from the samples into the getting started guide. Thoughts on that?

I like it.

Should they be? I guess the example app might be redundant if we have more granular examples. Although the example app has a test suite, and I don't believe the samples do.

I think autoinstrumentation should be there. I'm not sure what is the role of the example app, the only added value I see is that it includes the dependencies in setup.cfg, for the rest, it is completely covered in other examples. About tests, I think we should put tests in as many as possible examples.

If you don't mind I could try to do it as soon as I have some free time from the autoinstrumentation effort.

[toumorokoshi]

Sounds good! Thanks.