From 6f90089d63844da24e0aca987a87d6952ab1239e Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 27 Dec 2024 14:31:15 -0800 Subject: [PATCH] feedback: part1 --- CONTRIBUTING.md | 6 +++--- docs/general/how-to-define-semantic-conventions.md | 14 +++++++------- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b8ad09266f..47cb1289c1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -86,14 +86,14 @@ Come help us [decentralize semantic conventions](https://github.com/open-telemet ### Suggesting conventions for a new areas Defining semantic conventions involves a group of people who are familiar with the domain, -are involved into instrumentation efforts, and are committed to be the point of contact for +are involved with instrumentation efforts, and are committed to be the point of contact for pull requests, issues, and questions in this area. Check out [project management](https://github.com/open-telemetry/community/blob/main/project-management.md) for the details on how to start. -Refer to the [How to define new conventions](/docs/general/how-to-define-semantic-conventions.md) for -guidance. +Refer to the [How to define new conventions](/docs/general/how-to-define-semantic-conventions.md) +document for guidance. ### Prerequisites diff --git a/docs/general/how-to-define-semantic-conventions.md b/docs/general/how-to-define-semantic-conventions.md index 44f49309a6..4419132eb5 100644 --- a/docs/general/how-to-define-semantic-conventions.md +++ b/docs/general/how-to-define-semantic-conventions.md @@ -22,7 +22,7 @@ aliases: [how-to-define-new-semantic-conventions] This document describes requirements, recommendations, and best practices on how to define conventions -for the new areas or make substantial changes to the existing ones. +for new areas or make substantial changes to the existing ones. ## Defining new conventions @@ -40,14 +40,14 @@ Reuse existing attributes when possible. Look through [existing conventions](/do check out [common attributes](/docs/general/attributes.md). Semantic conventions authors are encouraged to use attributes from different namespaces. -Introduce new attributes when there is a clear use-case for them. Consider adding -them if most of the following apply: +Consider adding a new attribute when the following apply: -- They provide a clear benefit to end users by enhancing telemetry. -- You plan to use the attribute in spans, metrics, events, resources, or other telemetry signals. -- The attribute will be utilized in instrumentations. +- It provides a clear benefit to end users by enhancing telemetry. +- There is a clear plan to use the attribute in spans, metrics, events, resources, or other telemetry signals. +- There is a clear plan on how these attributes will be used by instrumentations -Postpone adding new attributes if their benefit to telemetry is not yet clear. +Semantic convention maintainers may reject the addition of a new attribute if its benefits +and use-cases are not yet clear. When defining a new attribute: