From 133949918018e1a8a846b53f393fbf2616a9a959 Mon Sep 17 00:00:00 2001
From: Liudmila Molkova <limolkova@microsoft.com>
Date: Tue, 30 Jul 2024 11:16:05 -0700
Subject: [PATCH] review 2

---
 .chloggen/1296.yaml                    |  2 +-
 .github/ISSUE_TEMPLATE/bug_report.yaml |  1 +
 docs/non-normative/code-generation.md  | 10 ++++++----
 3 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/.chloggen/1296.yaml b/.chloggen/1296.yaml
index 9427105e4f..8a1347f20a 100644
--- a/.chloggen/1296.yaml
+++ b/.chloggen/1296.yaml
@@ -1,4 +1,4 @@
 change_type: enhancement
-component: other
+component: docs
 note: Update semantic conventions code generation documentation to use weaver instead of build-tools.
 issues: [ 1296 ]
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml
index 40af0a175b..0f888909e0 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.yaml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yaml
@@ -16,6 +16,7 @@ body:
       multiple: true
       options:
         - area:other
+        - area:docs
         # NOTE: The list below is autogenerated using `make generate-gh-issue-templates`
         # DO NOT manually edit it.
         # Start semconv area list
diff --git a/docs/non-normative/code-generation.md b/docs/non-normative/code-generation.md
index 77996155cb..915ff4a738 100644
--- a/docs/non-normative/code-generation.md
+++ b/docs/non-normative/code-generation.md
@@ -63,7 +63,7 @@ This section contains suggestions on how to structure semantic convention artifa
 
 - Artifact name:
   - `opentelemetry-semconv` - stable conventions
-  - `opentelemetry-semconv-incubating` - (if applicable) the preview artifact containing all conventions
+  - `opentelemetry-semconv-incubating` - (if applicable) the preview artifact containing all (stable and experimental) conventions
 - Namespace: `opentelemetry.semconv` and `opentelemetry.semconv.incubating`
 - All supported Schema URLs should be listed to allow different instrumentations in the same application to provide the exact version of conventions they follow.
 - Attributes, metrics, and other convention definitions should be grouped by the convention type and the root namespace. See the example below:
@@ -129,13 +129,13 @@ templates:
       | map({
           root_namespace: .root_namespace,
           attributes: .attributes,
-          output: $output
+          output: $output + "attributes/"
         })
     application_mode: each
 ```
 
-You can configure language-specific parameters in the `params` section of the config or pass them with `--param key=value` arguments when
-running weaver command from the code generation script (similarly to build-tools `-Dparam=value` option).
+You can configure language-specific parameters in the `params` section of the config or pass them with `-DparamName=value` arguments when
+running weaver command from the code generation script (similarly to build-tools).
 
 Weaver is able to run code-generation for multiple templates (defined in the corresponding section) at once.
 
@@ -143,6 +143,8 @@ Before executing Jinja, weaver allows to filter or process semantic convention d
 In this example, it uses `semconv_grouped_attributes` filter - a helper method that groups attribute definitions by root namespace and excludes
 attributes not relevant to this language. You can write alternative or additional filters and massage semantic conventions data using [JQ](https://jqlang.github.io/jq/manual/).
 
+In certain cases, calling `semconv_grouped_attributes` with namespace exclusion and stability filters may be enough and then no port-processing is necessary.
+
 The `application_mode: each` configures weaver to run code generation for each semconv group and, as a consequence, generate code for each group
 in a different file. The application mode `single` is also supported to apply the template to all groups at once.