Refactor and update naming guidance (#1694)

Co-authored-by: Trask Stalnaker <[email protected]>

.chloggen/1694.yaml

@@ -0,0 +1,8 @@
+change_type: enhancement
+component: docs
+note: Update attribute, events, and metrics naming guidance to include new best practices.
+subtext: |
+  - Use namespaces (with `.` delimiter) whenever possible.
+  - Use precise, descriptive, unambiguous names that leave room for expansion.
+
+issues: [1694]

CONTRIBUTING.md

@@ -399,7 +399,7 @@ exists in some form in ECS, consider the following guidelines:
     data, user issue reports, feature requests, examples of prior work on a
     different standard or comparable evidence about the alternatives.
   - When no suitable alternatives are provided, altering an ECS name solely
-    for the purpose of complying with [Name Pluralization guidelines](docs/general/attribute-naming.md#name-pluralization-guidelines)
+    for the purpose of complying with [Name Pluralization guidelines](docs/general/naming.md#attribute-name-pluralization-guidelines)
     MAY BE avoided.
 - Do not use an existing ECS name as a namespace. If the name must differ, use a
   different namespace name to avoid clashes or avoid using the namespace

docs/attributes-registry/README.md

@@ -102,4 +102,4 @@ Currently, the following namespaces exist:
 - [VCS](vcs.md)
 - [Webengine](webengine.md)
 
-[developers recommendations]: ../general/attribute-naming.md#recommendations-for-application-developers
+[developers recommendations]: ../general/naming.md#recommendations-for-application-developers

docs/general/README.md

@@ -17,12 +17,3 @@ The following general Semantic Conventions are defined:
 * [Logs](logs.md): General Semantic Conventions for logs.
 * [Metrics](metrics.md): General Semantic Conventions for metrics.
 * [Spans](trace.md): General Semantic Conventions for traces / spans.
-
-## Event Name Reuse Prohibition
-
-A new event MUST NOT be added with the same name as an event that existed in
-the past but was renamed (with a corresponding schema file).
-
-When introducing a new event name check all existing schema files to make sure
-the name does not appear as a key of any "rename_events" section (keys denote
-old event names in rename operations).

docs/general/events.md

@@ -31,7 +31,7 @@ structure and semantics will also be defined.
 ## General event semantics
 
 * An event MUST have an [Event name property](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname)
-  that uniquely identifies the event. Event names are subject to the same rules as [attribute names](/docs/general/attribute-naming.md).
+  that uniquely identifies the event. Event names are subject to the [Naming guidelines](/docs/general/naming.md).
 * Event MAY have [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/common#attribute)
   attributes that provide additional context about the event.
 * It MAY contain a _payload_ (body) that describes the specific details of the