docs: typos and wordsmithing for 1.0.1 (cloudevents#733)

* docs: typos and wordsmithing for 1.1 This commit addresses a few typos and does a little wordsmithing on some of the docs and specs meant to land in the 1.1 release. In the proprietary-specs.md document, I used MUST in a couple of places. Not sure if this is appropriate for that doc. Signed-off-by: Lance Ball <[email protected]> * fixup: incorporate PR feedback Signed-off-by: Lance Ball <[email protected]> * fixup: incorporate PR feedback Signed-off-by: Lance Ball <[email protected]>
deissnerk · Dec 3, 2020 · 4661a69 · 4661a69
1 parent ffd3f74
commit 4661a69
Show file tree

Hide file tree

Showing 7 changed files with 43 additions and 43 deletions.
diff --git a/extensions/distributed-tracing.md b/extensions/distributed-tracing.md
@@ -2,9 +2,10 @@
 
 This extension embeds context from
 [Distributed Tracing](https://w3c.github.io/trace-context/) so that distributed
-systems can include traces that span an event-driven system. This extensions is meant
-to contain historical data of the parent trace, in order to diagnose eventual failures of the 
-systems through tracing platforms like Jaeger, Zipkin, etc.
+systems can include traces that span an event-driven system. This extension is
+meant to contain historical data of the parent trace, in order to diagnose
+eventual failures of the system through tracing platforms like Jaeger, Zipkin,
+etc.
 
 ## Attributes
 
@@ -35,10 +36,10 @@ if used, MUST carry the same trace information contained in protocol specific tr
 Given a multi hop event transmission, the Distributed Tracing Extension, if used, MUST 
 carry the trace information of the starting trace of the transmission. 
 In other words, it MUST NOT carry trace information of each individual hop, since this information is usually 
-carried using protocol specific defined headers, understood by tools like [OpenTelemetry](https://opentelemetry.io/).
+carried using protocol specific headers, understood by tools like [OpenTelemetry](https://opentelemetry.io/).
 
 Middleware between the source and the sink of the event could eventually add a Distributed Tracing Extension
-if the source didn't included any, in order to provide to the sink the starting trace of the transmission.
+if the source didn't include any, in order to provide to the sink the starting trace of the transmission.
 
 An example with HTTP:
 

diff --git a/http-protocol-binding.md b/http-protocol-binding.md
@@ -150,15 +150,15 @@ If a receiver detects the CloudEvents media type, but with an event format that
 it cannot handle, for instance `application/cloudevents+avro`, it MAY still
 treat the event as binary and forward it to another party as-is.
 
-When the `Content-Type` header is not prefixed with the CloudEvents media type,
-being able to know when the message ought to be attempted to be parsed as a
-CloudEvent can be a challenge. While this specification can not mandate that
-senders do not include any of the CloudEvents HTTP headers when the message
-is not a CloudEvent, it would be reasonable for a receiver to assume that if
-the message has all of the mandatory CloudEvents attributes as HTTP headers
-then it's probably a CloudEvent. However, as with all CloudEvent messages, if
-it does not adhere to all of the normative language of this specification
-then it is not a valid CloudEvent.
+When the `Content-Type` header value is not prefixed with the CloudEvents media
+type, knowing when the message ought to be parsed as a CloudEvent can be a
+challenge. While this specification can not mandate that senders do not include
+any of the CloudEvents HTTP headers when the message is not a CloudEvent, it
+would be reasonable for a receiver to assume that if the message has all of the
+mandatory CloudEvents attributes as HTTP headers then it's probably a
+CloudEvent. However, as with all CloudEvent messages, if it does not adhere to
+all of the normative language of this specification then it is not a valid
+CloudEvent.
 
 ### 3.1. Binary Content Mode
 

diff --git a/kafka-protocol-binding.md b/kafka-protocol-binding.md
@@ -51,8 +51,7 @@ of event messages with Kafka; it solely defines how CloudEvents are expressed
 in the Kafka protocol as [Kafka messages][kafka-message-format].
 
 The Kafka documentation uses "message" and "record" somewhat interchangeably and
-therefore the terms are to be considered being synonyms for this specification
-as well.
+therefore the terms are to be considered synonyms in this specification as well.
 
 Conceptually, Kafka is a log-oriented store for records, each holding a singular
 key/value pair. The store is commonly partitioned, and the partition for a
@@ -130,15 +129,14 @@ event format that it cannot handle, for instance
 `application/cloudevents+avro`, it MAY still treat the event as binary and
 forward it to another party as-is.
 
-When the `content-type` header is not prefixed with the CloudEvents
-media type, being able to know when the message ought to be attempted to be
-parsed as a CloudEvent can be a challenge. While this specification can not
-mandate that senders do not include any of the CloudEvents headers
-when the message is not a CloudEvent, it would be reasonable for a receiver
-to assume that if the message has all of the mandatory CloudEvents attributes
-as headers then it's probably a CloudEvent. However, as with all
-CloudEvent messages, if it does not adhere to all of the normative language of
-this specification then it is not a valid CloudEvent.
+When the `content-type` header value is not prefixed with the CloudEvents media
+type, knowing when the message ought to be parsed as a CloudEvent can be a
+challenge. While this specification can not mandate that senders do not include
+any of the CloudEvents headers when the message is not a CloudEvent, it would be
+reasonable for a receiver to assume that if the message has all of the mandatory
+CloudEvents attributes as headers then it's probably a CloudEvent. However, as
+with all CloudEvent messages, if it does not adhere to all of the normative
+language of this specification then it is not a valid CloudEvent.
 
 If the `content-type` header is not present then the receiver uses
 _structured_ mode with the JSON event format.

diff --git a/mqtt-protocol-binding.md b/mqtt-protocol-binding.md
@@ -126,15 +126,15 @@ If a receiver finds a CloudEvents media type as per the above rule, but with an
 event format that it cannot handle, for instance `application/cloudevents+avro`,
 it MAY still treat the event as binary and forward it to another party as-is.
 
-When the `Content Type` property is not prefixed with the CloudEvents
-media type, being able to know when the message ought to be attempted to be
-parsed as a CloudEvent can be a challenge. While this specification can not
-mandate that senders do not include any of the CloudEvents properties
-when the message is not a CloudEvent, it would be reasonable for a receiver
-to assume that if the message has all of the mandatory CloudEvents attributes
-as message properties then it's probably a CloudEvent. However, as with all
-CloudEvent messages, if it does not adhere to all of the normative language of
-this specification then it is not a valid CloudEvent.
+When the `Content Type` header value is not prefixed with the CloudEvents media
+type, knowing when the message ought to be parsed as a CloudEvent can be a
+challenge. While this specification can not mandate that senders do not include
+any of the CloudEvents properties when the message is not a CloudEvent, it would
+be reasonable for a receiver to assume that if the message has all of the
+mandatory CloudEvents attributes as message properties then it's probably a
+CloudEvent. However, as with all CloudEvent messages, if it does not adhere to
+all of the normative language of this specification then it is not a valid
+CloudEvent.
 
 With MQTT 3.1.1, the content mode is always _structured_ and the message payload
 MUST use the [JSON event format][json-format].

diff --git a/proprietary-specs.md b/proprietary-specs.md
@@ -11,7 +11,7 @@ the responsibility of the respective project maintainers.
 
 - Create a spec that follows the structure of an existing binding specification (e.g. [http](http-protocol-binding.md) or [amqp](amqp-protocol-binding.md)) - this will help SDK development.
   - **NOTES:**
-    - The spec needs to be publically accessible and managed by the proposing organization.
-    - The spec should clearly state the version(s) of CloudEvents supported.
+    - The spec must be publically accessible and managed by the proposing organization.
+    - The spec must clearly state the version(s) of CloudEvents supported.
 - Open a pull request against this file.
 - Respond to any comments on the pull request and potentially join one of the regularly scheduled working group sessions.
diff --git a/protobuf-format.md b/protobuf-format.md
@@ -93,7 +93,7 @@ message CloudEventAttributeValue {
 In this model an attribute's name is used as the map *key* and is
 associated with its *value* stored in the appropriately typed property.
 
-This approach allows for attributes to be represented and transported
+This approach allows attributes to be represented and transported
 with no loss of *type* information.
 
 ## 3. Data
@@ -140,7 +140,8 @@ Transports that support content identification MUST use the following designatio
 
 ## 5. Examples
 
-The following code-snippets shows how proto representations might be constucted asuming the availability of some convenience methods ...
+The following code-snippets show how proto representations might be constucted
+assuming the availability of some convenience methods.
 
 ### 5.1 Plain Text event data
 

diff --git a/websockets-protocol-binding.md b/websockets-protocol-binding.md
@@ -48,9 +48,9 @@ This specification does not prescribe rules constraining the use or handling of
 specific [HTTP target resource][rfc7230-section-5-1] to establish the WebSocket
 upgrade.
 
-This specification prescribe rules constraining the [WebSockets
+This specification prescribes rules constraining the [WebSockets
 Subprotocols][rfc6455-section-5-1] in order to reach agreement on the event
-format to use, in order to exchange serialized CloudEvents.
+format to use when sending and receiving serialized CloudEvents.
 
 Events are sent as WebSocket messages, serialized using an [event
 format][ce-event-format].
@@ -62,7 +62,7 @@ transferring events: _structured_ and _binary_.
 
 Because of the nature of WebSockets messages, this specification supports only
 _structured_ data mode, hence event metadata attributes and event data are
-placed into the WebSockets messages using an [event format][ce-event-format].
+sent in WebSocket messages using an [event format][ce-event-format].
 
 The [event format][ce-event-format] to be used in a full-duplex WebSocket stream
 is agreed during the [handshake](#14-handshake) and cannot change during the
@@ -123,7 +123,7 @@ specified WebSocket frame type:
 | `cloudevents.proto` | [Protobuf event format][proto-format] | Binary |
 
 All implementations of this specification MUST support the [JSON event
-format][json-format]. This specification doesn't support the [JSON batch
+format][json-format]. This specification does not support the [JSON batch
 format][json-batch-format].
 
 ### 1.6. Security
@@ -146,7 +146,7 @@ contains a CloudEvent serialized using the agreed event format.
 The chosen [event format][ce-event-format] defines how all attributes, including
 the payload, are represented.
 
-The event metadata and data MUST then be rendered in accordance with the event
+The event metadata and data MUST be rendered in accordance with the event
 format specification and the resulting data becomes the payload.
 
 ## 4. References