Reading semantic convention tables is cumbersome

[Oberon00]

(This has to be implemented in https://github.com/open-telemetry/build-tools/tree/main/semantic-conventions but affects mostly the spec and needs discussion, so opening issue here)

The current presentation of the semantic convention attribute tables has a few problems:

1. Some tables are too wide so you need horizontal scrolling. If the table is also very long, this becomes very awkward since you have to scroll down to scroll right and then scroll up again. E.g., https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/messaging.md#messaging-attributes and https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/http.md#common-attributes are such a tables on my screen.
2. The definitions of enum members are easy to miss since they come after the table and there is no hint that further information follows within the table (AFAIR previous versions of the semantic convention generator at least added "string enum" instead of just "string" as type, but this was removed). E.g. https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/messaging.md#messaging-attributes the destination_kind attribute.
3. The notes and required-conditions are annotated with [1], [2] etc. If you read the note, it is often not obvious to which attribute it belongs. This makes it impossible to read a semantic convention from top to bottom without scrolling up and down constantly. E.g. https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/messaging.md#messaging-attributes

Worst case currently is that you have a enum with a note and a condition and enum members can have a note as well. Sample UX:

• Read definition of enum in table. Scroll down to the note for the definition. Scroll up again because you forgot the number of the note for the condition. Scroll up again to continue reading in the table.
• Under the table, realize that this is an enum. Scroll up again to the definition and read it because you already forgot it.
• Scroll down again.
• Read the enum members. If its a long enum with many members, don't forget to scroll up and down repeatedly to read any notes on enum members.

I would like to have a presentation that you can read in a single pass without cross-referencing stuff below the table and inside the table. For example, this could be a presentation as a list, so there is enough space to inline the notes and enum definitions. This could be complemented by a (very) short list of attributes with links at the top.

[yurishkuro]

How important is it to even have the table? Looking at the examples you provided, not only do you need to scroll the table, but the formatting is also 80% whitespace. A bullet-list format would've been more compact:

• Attribute: messaging.system
• Type: string
• Required: Yes
• Description: A string identifying the messaging system.
• Examples: kafka; rabbitmq; activemq; AmazonSQS

And it allows more flexibility in adding clarifications / footnotes directly

[Oberon00]

I would use one bullet-point per attribute. Using a bullet-point per field per-attribute may be too much noise. E.g. your example I would write as:

Attributes:

• messaging.system: required string: A string identifying the messaging system.

  Note note note.

  Examples: kafka; rabbitmq; activemq; AmazonSQS

Or even more compact:

Attributes:

• messaging.system: required string: A string identifying the messaging system. (E.g.: kafka; rabbitmq; activemq; AmazonSQS)

  Note note note.

Non-required attributes would leave out the word "required".

[Blacksmoke16]

Github now has native support for footnotes: https://github.blog/changelog/2021-09-30-footnotes-now-supported-in-markdown-fields/.

Depending on how exactly things end up, they might provide a bit better experience versus plain text [n] matching.

[Oberon00]

I'd rather get rid of any footnote-like formatting completely. They are not really footnotes but often integral part of the attribute definition, where the text is just too long to reasonably fit in the table.