GITBOOK-3: Some structure fixes

SUMMARY.md

@@ -72,12 +72,13 @@
 * [Introduction](asynchronous-api-guidelines/01\_introduction/a\_introduction.md)
 * [Core Asynchronous Principles](asynchronous-api-guidelines/core-asynchronous-principles/README.md)
   * [Event Driven Architectures](asynchronous-api-guidelines/core-asynchronous-principles/b\_basic\_concepts\_edas.md)
-  * [Events](asynchronous-api-guidelines/core-asynchronous-principles/d\_basic\_concepts\_events/README.md)
-    * [Events as Notifications](asynchronous-api-guidelines/core-asynchronous-principles/d\_basic\_concepts\_events/events-as-notifications.md)
-    * [Events to Replicate Data](asynchronous-api-guidelines/core-asynchronous-principles/d\_basic\_concepts\_events/events-to-replicate-data.md)
+  * [Messages](asynchronous-api-guidelines/core-asynchronous-principles/messages/README.md)
+    * [Commands](asynchronous-api-guidelines/core-asynchronous-principles/messages/commands.md)
+    * [Queries](asynchronous-api-guidelines/core-asynchronous-principles/messages/query.md)
+    * [Events](asynchronous-api-guidelines/core-asynchronous-principles/messages/d\_basic\_concepts\_events/README.md)
+      * [Events as Notifications](asynchronous-api-guidelines/core-asynchronous-principles/messages/d\_basic\_concepts\_events/events-as-notifications.md)
+      * [Events to Replicate Data](asynchronous-api-guidelines/core-asynchronous-principles/messages/d\_basic\_concepts\_events/events-to-replicate-data.md)
   * [Protocols](asynchronous-api-guidelines/core-asynchronous-principles/j\_protocols.md)
-  * [Commands](asynchronous-api-guidelines/core-asynchronous-principles/commands.md)
-  * [Query](asynchronous-api-guidelines/core-asynchronous-principles/query.md)
   * [Coupling](asynchronous-api-guidelines/core-asynchronous-principles/coupling.md)
   * [Bounded Context](asynchronous-api-guidelines/core-asynchronous-principles/bounded-context.md)
   * [Stream Processing](asynchronous-api-guidelines/core-asynchronous-principles/stream-processing.md)
@@ -94,8 +95,8 @@
   * [Key/Value Format](asynchronous-api-guidelines/kafka-asynchronous-guidelines/g\_key\_value\_format.md)
   * [Message Headers](asynchronous-api-guidelines/kafka-asynchronous-guidelines/h\_message\_headers.md)
   * [Specification Granularity](asynchronous-api-guidelines/kafka-asynchronous-guidelines/d\_spec\_granularity.md)
-  * [Meaningful Descriptions](asynchronous-api-guidelines/kafka-asynchronous-guidelines/e\_meaningful\_descriptions.md)
-  * [Self-Contained Specifications](asynchronous-api-guidelines/kafka-asynchronous-guidelines/f\_self\_contained\_specs.md)
+  * [Self-Contained Specifications](asynchronous-api-guidelines/kafka-asynchronous-guidelines/f\_self\_contained\_specs/README.md)
+    * [Meaningful Descriptions](asynchronous-api-guidelines/kafka-asynchronous-guidelines/f\_self\_contained\_specs/e\_meaningful\_descriptions.md)
   * [Schema Data Evolution](asynchronous-api-guidelines/kafka-asynchronous-guidelines/f\_schema\_data\_evolution/README.md)
     * [Backward Compatibility](asynchronous-api-guidelines/kafka-asynchronous-guidelines/f\_schema\_data\_evolution/backward-compatibility.md)
     * [Forward Compatibility](asynchronous-api-guidelines/kafka-asynchronous-guidelines/f\_schema\_data\_evolution/forward-compatibility.md)

asynchronous-api-guidelines/core-asynchronous-principles/coupling.md

@@ -2,7 +2,7 @@
 
 The term coupling can be understood as the impact that a change in one component will have on other components. In the end, it is related to the amount of things that a given component shares with others. The more is shared, the more tight is the coupling.
 
-**Note:** A tighter coupling is not necessarily a bad thing, it depends on the situation. It will be necessary to assess the tradeoff between provide as much information as possible and to avoid having to change several components as a result of something changing in other component.
+**Note:** A tighter coupling is not necessarily a bad thing, it depends on the situation. It will be necessary to assess the trade-off between providing as much information as possible and to avoid having to change several components as a result of something changing in other component.
 
 The coupling of a single component is actually a function of these factors:
 

asynchronous-api-guidelines/core-asynchronous-principles/j_protocols.md

@@ -9,3 +9,5 @@ The accepted protocols for asynchronous APIs are:
 * **HTTPS**
 * **WebSockets**
 * **MQTT**
+
+**Note** Guidelines for non-kafka protocols are not available at this point, but they might be added in the future.

asynchronous-api-guidelines/core-asynchronous-principles/messages/README.md

@@ -0,0 +1,7 @@
+# Messages
+
+A message in general is a piece of information that travels from an emitter to a receiver. There are different types of messages:
+
+* Commands
+* Queries
+* Events

asynchronous-api-guidelines/kafka-asynchronous-guidelines/d_spec_granularity.md

@@ -1,7 +1,7 @@
 # Specification Granularity
 
-In adidas all resources are grouped by namespace.
+In adidas streaming platform, all resources are grouped by namespaces.
 
 For that reason specs **SHOULD** be created with a relation 1:1 with namespaces. In other words, every namespace will have an AsyncAPI spec including all the assets belonging to that namespace.
 
-Different granularities **MAY** be chosen depending on the needs. 
+Different granularities **MAY** be chosen depending on the needs.

asynchronous-api-guidelines/kafka-asynchronous-guidelines/e_meaningful_descriptions.md

@@ -1,3 +0,0 @@
-# Meaningful Descriptions
-
-All fields included in the specs **MUST** include a proper description. 

asynchronous-api-guidelines/kafka-asynchronous-guidelines/f_schema_data_evolution/backward-compatibility.md

@@ -7,9 +7,9 @@ There are two variants here:
 
 The operations that preserve backward compatibility are:
 
-* Delete fields
+* Deleting fields
   * Consumers with the newer version will just ignore the non-existing fields
-* Add optional fields (with default values)
+* Adding optional fields (with default values)
   * Consumers will set the default value for the missing fields in their schema version
 
 <figure><img src="../../../.gitbook/assets/spaces_PQHX3w20BF4lnkckLJzC_uploads_git-blob-17547da367c50d28e6996ea1d3fab4d10625765b_sr_backward_compatibility.png" alt=""><figcaption></figcaption></figure>

asynchronous-api-guidelines/kafka-asynchronous-guidelines/f_schema_data_evolution/forward-compatibility.md

@@ -9,7 +9,7 @@ The operations that preserve forward compatibility are:
 
 * Adding a new field
   * Consumers will ignore the fields that are not defined in their schema version
-* Delete optional fields (with default values)
+* Deleting optional fields (with default values)
   * Consumers will use the default value for the missing fields defined in their schema version
 
 <figure><img src="../../../.gitbook/assets/spaces_PQHX3w20BF4lnkckLJzC_uploads_git-blob-8139077e602e7c36543a4977fcb8655313e8f1b9_sr_forward_compat.png" alt=""><figcaption></figcaption></figure>

asynchronous-api-guidelines/kafka-asynchronous-guidelines/f_schema_data_evolution/full-compatibility.md

@@ -10,6 +10,6 @@ This is a combination of both compatibility types (backward and forward). It als
 This mode is preserved only if using the following operations
 
 * Adding optional fields (with default values)
-* Delete optional fields (with default values)
+* Deleting optional fields (with default values)
 
 <figure><img src="../../../.gitbook/assets/spaces_PQHX3w20BF4lnkckLJzC_uploads_git-blob-effb69104100a69f6101daee3cb01a88dded13d4_sr_full_compat.png" alt=""><figcaption></figcaption></figure>

asynchronous-api-guidelines/kafka-asynchronous-guidelines/f_self_contained_specs/README.md

@@ -1,3 +1,3 @@
 # Self-Contained Specifications
 
-All AsyncAPI specification **SHOULD** include as much information as needed in order to make the spec self-contained and clearly documented
+All AsyncAPI specification **SHOULD** include as much information as needed in order to make the spec self-contained and clearly documented.

asynchronous-api-guidelines/kafka-asynchronous-guidelines/f_self_contained_specs/e_meaningful_descriptions.md

@@ -0,0 +1,3 @@
+# Meaningful Descriptions
+
+AsyncAPI specs **MUST** make use of the _description_ fields, including there meaningful information to understand the purpose of the different elements.