Apply suggestions from code review

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

Author: Liudmila Molkova

.chloggen/1716.yaml

@@ -1,4 +1,4 @@
 change_type: enhancement
 component: docs, db
-note: Add common guidance on recording errors on spans and metrics, clarify DB conventions.
+note: Add common guidance for recording errors on spans and metrics, clarify DB conventions.
 issues: [1536, 1716]

docs/exceptions/README.md

@@ -18,7 +18,7 @@ Semantic conventions for Exceptions are defined for the following signals:
 
 **Status**: [Development][DocumentStatus]
 
-When instrumented operation fails with an exception, instrumentation SHOULD record
+When an instrumented operation fails with an exception, instrumentation SHOULD record
 this exception as a [span event](exceptions-spans.md) or a [log record](exceptions-logs.md).
 
 Recording exceptions on spans SHOULD be accompanied by
@@ -28,16 +28,16 @@ Recording exceptions on spans SHOULD be accompanied by
 Refer to the [Recording errors](/docs/general/recording-errors.md) document for additional
 details on how to record errors across different signals.
 
-It's RECOMMENDED to use `Span.recordException` API or logging library API that takes exception instance
+It's RECOMMENDED to use the `Span.recordException` API or logging library API that takes exception instance
 instead of providing individual attributes. This enables the OpenTelemetry SDK to
 control what information is recorded based on application configuration.
 
 It's NOT RECOMMENDED to record the same exception more than once.
 It's NOT RECOMMENDED to record exceptions that are handled by the instrumented library.
 
-For example, in this code-snippet, `ResourceNotFoundException` is handled and corresponding
-native instrumentation should not record it. Other exceptions, that are propagated
-to the caller, should be recorded (or logged) once.
+For example, in this code-snippet, `ResourceAlreadyExistsException` is handled and the corresponding
+native instrumentation should not record it. Exceptions which are propagated
+to the caller should be recorded (or logged) once.
 
 ```java
 public boolean createIfNotExists(String resourceId) throws IOException {

docs/general/recording-errors.md

@@ -6,14 +6,14 @@ linkTitle: Recording errors
 
 **Status**: [Development][DocumentStatus].
 
-This document provides recommendations to semantic conventions and instrumentation authors
+This document provides recommendations to semantic convention and instrumentation authors
 on how to record errors on spans and metrics.
 
 Individual semantic conventions are encouraged to provide additional guidance.
 
 ## What constitutes an error
 
-Operation SHOULD be considered as failed if any of the following is true:
+An operation SHOULD be considered as failed if any of the following is true:
 
 - an exception is thrown by the instrumented method (API, block of code, or another instrumented unit)
 - the instrumented method returns an error in another way, for example, via an error code
@@ -31,7 +31,7 @@ Operation SHOULD be considered as failed if any of the following is true:
   > Instrumentations that have additional context about a specific request MAY use
   > this context to set the span status more precisely.
 
-Errors that were retried or handled allowing operation to complete gracefully SHOULD NOT
+Errors that were retried or handled (allowing an operation to complete gracefully) SHOULD NOT
 be recorded on spans or metrics that describe this operation.
 
 ## How to record errors on spans

docs/http/http-spans.md

@@ -117,7 +117,7 @@ the client or server from sending/receiving the request/response fully.
 When instrumentation detects such errors it SHOULD set span status to `Error`
 and SHOULD set the `error.type` attribute.
 
-Refer to the [Recording Errors](/docs/general/recording-errors.md) document for
+**Status**: [Development][DocumentStatus] - Refer to the [Recording Errors](/docs/general/recording-errors.md) document for
 general considerations on how to record span status.
 
 ## HTTP client