feedback

lmolkova · Jan 11, 2025 · d09cce3 · d09cce3
1 parent d3da146
commit d09cce3
Show file tree

Hide file tree

Showing 2 changed files with 6 additions and 2 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -14,7 +14,7 @@ requirements and recommendations.
 - [Sign the CLA](#sign-the-cla)
 - [How to Contribute](#how-to-contribute)
   - [Which semantic conventions belong in this repo](#which-semantic-conventions-belong-in-this-repo)
-  - [Suggesting conventions for a new areas](#suggesting-conventions-for-a-new-areas)
+  - [Suggesting conventions for a new area](#suggesting-conventions-for-a-new-area)
   - [Prerequisites](#prerequisites)
   - [1. Modify the YAML model](#1-modify-the-yaml-model)
     - [Code structure](#code-structure)

diff --git a/docs/general/how-to-define-semantic-conventions.md b/docs/general/how-to-define-semantic-conventions.md
@@ -34,6 +34,10 @@ for new areas or make substantial changes to the existing ones.
 
 ### Best practices
 
+> [!NOTE]
+>
+> This section contains non-normative guidance.
+
 #### Defining attributes
 
 Reuse existing attributes when possible. Look through [existing conventions](/docs/attributes-registry/) for similar areas,
@@ -89,7 +93,7 @@ Consider the scope of the attribute and how it may evolve in the future:
   For example, if creating a system-specific attribute, evaluate whether other systems
   in the same domain might need a similar attribute in the future.
 
-  Similarly, instead of defining a simple boolean flag like `foo.is_error`, consider a
+  Similarly, instead of defining a simple boolean flag indicating a success or failure, consider a
   more extensible approach, such as using a `foo.status_code` attribute to include additional details.
 
 - When defining a broad attribute applicable across multiple domains or systems,