Improve OpenTelemetry entity documentation

[alanwest]

No description provided.

[CLAassistant]

All committers have signed the CLA.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[github-actions]

Hi @alanwest 👋

Thanks for your pull request! Your PR is in a queue, and a writer will take a look soon. We generally publish small edits within one business day, and larger edits within three days.

We will automatically generate a preview of your request, and will comment with a link when the preview is ready (usually 10 to 20 minutes).

[netlify]

✅ Deploy Preview for docs-website-netlify ready!

Name	Link
🔨 Latest commit	0925748
🔍 Latest deploy log	https://app.netlify.com/sites/docs-website-netlify/deploys/663a87d81222670008b9bb9b
😎 Deploy Preview	https://deploy-preview-17188--docs-website-netlify.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[jack-berg]

Couple comments but looks good

[jack-berg]

Couple presentation questions:

• If you want this to show up in the in-page navigation, you need to it to use the same header level as the top level used on the page. So since you use an h2 above, anything lower than h2 like this h3 will be omitted.
• What do you think about a table to represent this information?

Type	Required attributes	Recommended attributes	Entity tags
service	service.name	service.instance.id - Enables faceting between multiple instances of the same service. telemetry.sdk.language - Drives display of language specific runtime UIs, like the JVM runtime page for Java	service.namespace telemetry.sdk.language telemetry.sdk.version k8s.cluster.name k8s.namespace.name k8s.deployment.name

The list view allows for more detailed description, but the tabular view increases information density. List is the conservative approach since we may likely find ourselves needing to give longer explanations.

[alanwest]

List is the conservative approach since we may likely find ourselves needing to give longer explanations.

A table layout was my first intuition too but settled on a list for now for this reason pretty much... I suspect we will iterate on this a bit more - maybe adding additional entity types - before we're completely done with our holistic refactor of the otel docs.

I do agree the lists explode the length of the page. I thought about collapsable regions like we use elsewhere in the docs, but I hate those things so much.

That said, no strong opinions yet...

[alanwest]

If you want this to show up in the in-page navigation

I conceded and did not promote everything to h2. I think the right hand nav is not too terrible as I've organized it.

• Supported entity types
• Supported entity relationships
• Adding custom tags to an entity

@ally-sassman This is a topic Jack and I have discussed.. The right hand nav is a pretty standard pattern in technical documentation. But I think NR's implementation has a lot to be desired.

OpenTelemetry.io is a great example of the pattern applied well.

For example, check out the awesome right hand nav on this page:
https://opentelemetry.io/docs/concepts/signals/traces/

[jack-berg]

The right hand nav is a pretty standard pattern in technical documentation. But I think NR's implementation has a lot to be desired.

I think all it would take would be two levels of headers to be included instead of one.

[ally-sassman]

@jack-berg @alanwest I agree that the right nav can and should be improved. I believe our eng team is currently working on the ability to display H3s in the right nav. In the meantime, let's keep writing strong titles for headers keeping the right-nav presentation in mind.

[jack-berg]

Consider renaming the name of this page from "OpenTelemetry resources: Best practices". Maybe just "OpenTelemetry Resources"?

[alanwest]

I just left it as is since all the pages that are siblings to this one has the awkward "Best practices" subtitle. May be we just fix them all at once when we get everything moved to where we ultimately want it.