[processor/transform] more readme refactoring

[TylerHelmuth]

Description

With the new context inference feature the user needs to know less about the concept of an OTTL Context. This refactor restructures the README some more to try really hard not to talk about OTTL context and instead talk about OTTL Paths, which is the concrete thing the user needs to know to write an OTTL statement.

Link to tracking issue

#29017

[evan-bradley]

Overall I really like this. I'd be fine moving forward without any of the larger changes I suggested, we can always iterate later.

[edmocosta]

It looks great! I liked the new format and extra OTTL section.

[edmocosta]

Would we be able to get away without introducing any new concepts and just say that each item in the X_statements list is:
"Basic config": A statement
"Advanced config": A nested config object within the list that contains a list of statements and options for configuring their > execution.

It's getting great! I liked @evan-bradley suggestion, but reading the docs it's still feel we're introducing new concepts, but now with different names "Flat configuration" -> "Basic Config", and "Structured configuration" -> "Advanced Configuration". I'm wondering if we should focus on the statements configuration part instead, so it wouldn't feel those styles are completely different configuration formats, for example: TylerHelmuth/opentelemetry-collector-contrib@transform-continue-readme-refactor...edmocosta:opentelemetry-collector-contrib:patch-1

[evan-bradley]

I'm wondering if we should focus on the statements configuration part instead, so it wouldn't feel those styles are completely different configuration formats

I was hoping that at least with terms like "basic" or "advanced" configuration users would have some pre-existing idea of what those mean, but I agree we should try to make them feel like the same thing.

I like what you're going for, but I think I would tweak it just slightly and say something like this:

The Transform Processor's main config section is a list of things for the processor to execute. The list can contain:

1. A string, which is a statement to execute. Most users should opt for this, at least at first.
2. A subobject, which allows users advanced configuration options applied to a sub-list of statements, including conditions, a specific error mode, etc. (note all statements here must work on the same type of data).

I think if we frame it as "diving deeper" instead of making a choice between two styles they will feel like a single thing.

[edmocosta]

LGTM! Thanks for improving the docs!

[evan-bradley]

Looks good to me. This is a big improvement for the docs.