clean up

docs/general/group-stability.md

@@ -10,14 +10,15 @@ aliases: [semantic-convention-groups]
 Spans, metrics, events, and resources are defined in semantic convention groups in YAML schema.
 Each group has a `type` property that could be one of the following:
 
-- `attribute_group` - non-signal specific group of attributes. It does not describe a
-  semantic convention and is usually used for auxiliary purposes.
 - `span` - defines semantic convention for a specific type of span, such as HTTP `CLIENT`
 - `metric` - defines semantic convention for a specific metric, such as HTTP client request duration
 - `event` - defines semantic conventions for a specific event, such as exception.
 - `resource` - defines semantic conventions for a specific entity the telemetry is collected within,
   such as `service`.
 
+Groups that have `attribute_group` type do not describe semantic convention and
+are used for auxiliary purposes.
+
 All semantic convention groups have the following common properties:
 
 - identity - TODO - identifies span type, metric instrument name, or event name
@@ -30,24 +31,26 @@ All semantic convention groups have the following common properties:
   replacement or other details.
 - `attributes` lists references to applicable attributes in the [registry](../attributes-registry/README.md)
 
-In addition to common properties, convention group can have type-specific properties, see
+In addition to common properties, semantic convention groups have type-specific properties, see
 [Schema documentation](https://github.com/open-telemetry/weaver/blob/main/schemas/semconv-syntax.md)
 for the details.
 
 ## Group Stability
 
-Semantic Convention groups can be `stable`
-(corresponds to [Stable maturity level](https://github.com/open-telemetry/oteps/blob/main/text/0232-maturity-of-otel.md#stable))
-or `experimental` (corresponds to [Alpha maturity level](https://github.com/open-telemetry/oteps/blob/main/text/0232-maturity-of-otel.md#alpha))
-if stability level is not specified (TODO), it's assumed to be `experimental`.
+TODO: adopt new maturity levels.
+
+Semantic Convention groups can be `stable` (corresponds to
+[Stable maturity level](https://github.com/open-telemetry/oteps/blob/main/text/0232-maturity-of-otel.md#stable))
+or `experimental` (corresponds to [Development maturity level](https://github.com/open-telemetry/oteps/blob/main/text/0232-maturity-of-otel.md#alpha))
+if stability level is not specified, it's assumed to be `experimental`.
 
 Group stability MUST NOT change from `stable` to `experimental`.
 
 Identifiable (TODO) semantic convention group MUST NOT be removed even if it's `experimental`
 to allow code generation and preserve documentation for legacy instrumentations.
 
-When a group is no longer recommended or supported, it SHOULD be deprecated.
-When a group is renamed, the existing group SHOULD be deprecated in favor of a new convention.
+When group is no longer recommended or supported, it SHOULD be deprecated.
+When group is renamed, the existing group SHOULD be deprecated in favor of a new convention.
 
 See [Versioning and Stability](https://opentelemetry.io/docs/specs/otel/versioning-and-stability/#semantic-conventions-stability)
 for the details on stability guarantees provided for specific group types.
@@ -57,7 +60,7 @@ for the details on stability guarantees provided for specific group types.
 Semantic convention groups MAY reference attributes with stability levels different
 from a group level.
 
-Stability guarantees on the group apply to group properties (such as type, identity and
+Stability guarantees on the group level apply to group properties (such as type, identity and
 signal-specific properties) and a subset of stable attributes used within this group.
 
 Experimental group of any type:
@@ -83,8 +86,9 @@ Stable group:
 - stable attributes MUST NOT be removed from a stable group.
 - requirement level of a stable attribute SHOULD NOT change
 
+### Examples of allowed and not allowed changes
 
-### Stable group and **stable** attribute
+#### Stable group and **stable** attribute
 
 | Change                                                  | Is change allowed?                     | Description |
 | ------------------------------------------------------- | -------------------------------------- | ----------- |
@@ -98,7 +102,7 @@ Stable group:
 | Changing sampling_relevant value on a span attribute    | not allowed, there could be exceptions | Depending on requirement level |
 | Changing brief, description, examples                   | yes                                    | As long as it does not change the meaning of the attribute |
 
-### Stable group and **experimental** attribute
+#### Stable group and **experimental** attribute
 
 | Change                                                  | Is change allowed?                     | Description |
 | ------------------------------------------------------- | -------------------------------------- | ----------- |
@@ -109,4 +113,3 @@ Stable group:
 | Changing requirement level                              | not allowed                            | Experimental attributes can only be opt-in on stable groups |
 | Changing sampling_relevant value on a span attribute    | yes                                    |  |
 | Changing brief, description, examples                   | yes                                    |  |
-