docs: make metadata field description more clear

[jkowalleck]

fixes #345
fixes #273

---

parts are superseded by #378
parts are continued in #379

[lfrancke]

Looks good, only minor nitpicks

[stevespringett]

Any reason why BOM was changed to document?

[jkowalleck]

Any reason why BOM was changed to document?

Because the described fields do not only apply to BOM, but also to VEX, VDR and anything else that we do not have considered as a use case. It is a general-purpose field not bound to any specific purpose, right?

[mrutkows]

Since there is a dedicated PR specific to the manufacturer descriptive text, perhaps leave it out of this one and then link them making this one a pre-req of the the other.

[jkowalleck]

Since there is a dedicated PR specific to the manufacturer descriptive text, perhaps leave it out of this one and then link them making this one a pre-req of the the other.

no need to think about such things. this is what SCM is for, and it will handle it.
especially since this PR is about documentation, and the other one is about a feature (that involves some documentation).

the actual thing we need to think about are the possible breaking changes that are coming with the documentation.

[jkowalleck]

@mrutkows you requested a change of this PR (via your review),
but i do not understand that you want to have changed. Could you clarify?

[jkowalleck]

I took your comments and will propose an alternative solution,
which is highly driven by #372 (comment)

[stevespringett]

I prefer "BOM" to "document". Yes, I know that CycloneDX does other things, but its primarily a BOM format. A "document" is not applicable to protobuf and any JSON/XML over an API. The word "document" just feeds wrong, feels old

[jkowalleck]

closed this PR>
all intended changes were superseded by other PRs, or were not solvable in a non-breaking way