Subscriptions section review (#16)

* first draft

* update

* update

* update

* fix conflict

* final additions

* fixes

* first draft

* update

* update

* final additions

* fixing conflicts

* fixing conflicts

* Apply suggestions from code review

Co-authored-by: angrykoala <[email protected]>

---------

Co-authored-by: angrykoala <[email protected]>

Author: lidiazuin

modules/ROOT/content-nav.adoc

@@ -40,11 +40,11 @@
 *** xref:mutations/delete.adoc[]
 
 ** xref:subscriptions/index.adoc[]
-*** xref:subscriptions/getting-started.adoc[Getting Started]
+*** xref:subscriptions/getting-started.adoc[Getting started]
 *** xref:subscriptions/events.adoc[Events]
 *** xref:subscriptions/filtering.adoc[]
 *** xref:subscriptions/scaling.adoc[]
-*** xref:subscriptions/engines.adoc[Subscriptions Engines]
+*** xref:subscriptions/engines.adoc[Engines]
 
 ** xref:custom-resolvers.adoc[]
 

modules/ROOT/images/subscriptions/diagram1.png

@@ -1,13 +1,14 @@
 [[subscription-engines]]
-= Engines
-
-There are different ways to how a GraphQL subscription may be set along with `@neo4j/graphql` server.
+:description: This page describes how a GraphQL subscription may be set along with a @neo4j/graphql server.
+= Subscription engines
 
+This page describes different ways to set up a GraphQL subscription along with a `@neo4j/graphql` server.
 
 == Default
+
 The default behavior is automatically set if the `subscriptions` feature is set to `true`, as described in xref::subscriptions/getting-started.adoc[Getting Started]:
 
-[source, javascript]
+[source, javascript, indent=0]
 ----
 new Neo4jGraphQL({
     typeDefs,
@@ -18,11 +19,13 @@ new Neo4jGraphQL({
 });
 ----
 
-This behavior enables a simple subscription system that will work on a single instance, which is ideal for development, testing, and servers that do not require horizontal scaling.
+This behavior enables a simple subscription system that works on a single instance.
+It is ideal for development, testing, and servers that do not require horizontal scaling.
 
 [[amqp]]
 == AMQP
-Using subscriptions on a server with multiple instances can be tricky, as described in xref::subscriptions/scaling.adoc[Horizontal Scaling]. 
+
+Using subscriptions on a server with multiple instances can be complex, as described in xref::subscriptions/scaling.adoc[Horizontal scaling]. 
 Therefore, the recommended approach is to use a PubSub system, which can be achieved with an AMQP broker such as link:https://www.rabbitmq.com/[RabbitMQ]. 
 This is supported by the link:https://www.npmjs.com/package/@neo4j/graphql-amqp-subscriptions-engine[@neo4j/graphql-amqp-subscriptions-engine] package.
 
@@ -36,19 +39,22 @@ Some brokers supporting this protocol are:
 
 The plugin can be installed with `npm`:
 
-[source, bash]
+[source, sh, indent=0]
 ----
 npm install @neo4j/graphql-amqp-subscriptions-engine
 ----
 
-NOTE: AMQP 1.0 is **not** supported by this plugin.
+[NOTE]
+====
+AMQP 1.0 is **not** supported by this plugin.
+====
 
 === Usage
 
 The AMQP plugin should be instanced and passed to the `subscription` field in features.
-This will automatically enable the subscriptions with the AMQP broker as a message queue:
+This automatically enables the subscriptions with the AMQP broker as a message queue:
 
-[source, javascript]
+[souce, javascript, indent=0]
 ----
 const { Neo4jGraphQLAMQPSubscriptionsEngine } = require("@neo4j/graphql-amqp-subscriptions-engine");
 
@@ -72,33 +78,37 @@ const neoSchema = new Neo4jGraphQL({
 === API
 The following options can be passed to the constructor:
 
-* **connection**: An AMQP uri as a string or a configuration object.
-** **hostname**: Hostname to be used, defaults to `localhost`.
+* **connection**: an AMQP uri as a string or a configuration object.
+** **hostname**: hostname to be used. 
+Defaults to `localhost`.
 ** **username**: defaults to `guest`.
 ** **password**: defaults to `guest`.
-** **port**: Port of the AMQP broker, defaults to `5672`.
-* **exchange**: The exchange to be used in the broker. Defaults to `neo4j.graphql.subscriptions.fx`.
-* **version**: The AMQP version to be used. Currently only `0-9-1` is supported.
+** **port**: port of the AMQP broker.
+Defaults to `5672`.
+* **exchange**: the exchange to be used in the broker. 
+Defaults to `neo4j.graphql.subscriptions.fx`.
+* **version**: the AMQP version to be used. 
+Currently only `0-9-1` is supported.
 
 Additionally, any option supported by link:https://www.npmjs.com/package/amqplib[amqplib] can be passed to `connection`.
-
-==== Methods
+To set these configurations up, use the following method:
 
 * **close(): Promise<void>**: Closes the connection and channel created, and unbinds the event emitter.
 
 [[custom-subscription]]
-== Custom Subscription Engine
+== Custom subscription engine
+
 If none of the existing engines is valid for your use case, you can create a new engine to connect to any broker you may need. 
 For that, you need to create a new class defining your messaging behavior and it must contain:
 
 * An `EventEmitter` property called `events` that should emit an event every time the broker sends a message.
-* A `publish` method that will publish a new event to the broker.
-* Optionally, an `init` method returning a promise that will be called on `getSchema`. 
+* A `publish` method that should publish a new event to the broker.
+* Optionally, an `init` method returning a promise that should be called on `getSchema`. 
 This is useful for setting up the connection to a broker.
 
 In case you want to handle subscriptions using link:https://redis.io/[redis]:
 
-[source, javascript]
+[souce, javascript, indent=0]
 ----
 // Note: This is an example of a custom subscription behavior and not a production ready redis implementation.
 class CustomRedisSubscriptionEngine {
@@ -139,9 +149,10 @@ const neoSchema = new Neo4jGraphQL({
 ----
 
 Note that extra properties and methods are often needed to handle the connection to the broker.
-As long as the messages are sent to the broker in the `publish` method and that these messages are received and then emitted through the `events` property, the subscriptions will be properly handled.
+However, as long as the messages are sent to the broker in the `publish` method and that these messages are received and then emitted through the `events` property, the subscriptions are properly handled.
 
 === Using Typescript
+
 If using Typescript, you may import the interface `Neo4jGraphQLSubscriptionsEngine` to implement your own class.
 Ensure the API is correctly defined:
 
@@ -152,6 +163,7 @@ class CustomRedisEngine implements Neo4jGraphQLSubscriptionsEngine {}
 
 [NOTE]
 ====
-Events are sent to the class in order, however, order is not guaranteed once these events have been broadcasted through a broker.
+Events are sent in order to the class.
+However, order is not guaranteed once these events have been broadcasted through a broker.
 For cases when ordering is important, you must set up the field `timestamp` in the subscriptions payload.
 ====