docs: Update outdated documentation and fix small grammar or spelling mistakes (aws#107)

- Update all outdated documentation to account for changes made to the utility.
- Proofread and edit grammar or spelling mistakes
- Update outdated images that are referenced in the docs

Updated documentation list:
- CHANGELOG.md
- README.md
- doc/cdk.md
- doc/routesExample.md
- doc/todoExample.md
- samples/airports.source.schema.graphql

Updated images:
- doc/images/AppSyncQuery.png
- doc/images/todoCreate.png
- doc/images/todoGetTodos.png
- doc/images/todoNestedQuery.png

---------

Co-authored-by: andreachild <andrea.child@improving.com>
Co-authored-by: Kris McGinnes <kris@mcginnes.io>

Author: 3 people

CHANGELOG.md

@@ -61,4 +61,5 @@ This release contains new support for Apollo Server integration.
 * Enabled mutations for the Apollo Server ([#98](https://github.com/aws/amazon-neptune-for-graphql/pull/98))
 * Refactored integration tests to be less vulnerable to resolver logic changes ([#99](https://github.com/aws/amazon-neptune-for-graphql/pull/99))
 * Enabled usage of query fragments with Apollo Server ([#103](https://github.com/aws/amazon-neptune-for-graphql/pull/103))
-* Compressed resolver schema file and moved schema initialization outside of event handlers to improve performance ([#111](https://github.com/aws/amazon-neptune-for-graphql/pull/111))
+* Compressed resolver schema file and moved schema initialization outside of event handlers to improve performance ([#111](https://github.com/aws/amazon-neptune-for-graphql/pull/111))
+* Updated and proofread outdated documentation ([#107](https://github.com/aws/amazon-neptune-for-graphql/pull/107))

README.md

@@ -5,9 +5,13 @@
 
 The Amazon Neptune utility for GraphQL™ is a Node.js command-line utility to help with the creation and maintenance of a GraphQL API for the Amazon Neptune Database or Neptune Analytics graph. It is a no-code solution for a GraphQL resolver when GraphQL queries have a variable number of input parameters and return a variable number of nested fields.
 
-If you **start from a Neptune database with data**, the utility discover the graph database schema including nodes, edges, properties and edges cardinality, generate the GraphQL schema with the directives required to map the GraphQL types to the graph databases nodes and edges, and auto-generate the resolver code. We optimized the resolver code to reduce the latency of querying Amazon Neptune by returning only the data requested by the GraphQL query. *(Note: the utility works only for Property Graph databases, not RDF yet)*
+If you **start from a Neptune database with data**, the utility discovers the graph database schema including nodes, edges, properties and edges cardinality. This database schema is then used to generate the GraphQL schema with the directives required to map the GraphQL types to the graph databases nodes and edges, and auto-generate the resolver code. We optimized the resolver code to reduce the latency of querying Amazon Neptune by returning only the data requested by the GraphQL query.
 
-You can also **start with a GraphQL schema with your types and an empty Neptune database**. The utility will process your starting GraphQL schema and inference the directives required to map it to the Neptune database graph nodes and edges. You can also **start with GraphQL schema with the directives**, that you have modified or created.
+> [!NOTE]
+> 
+> This utility works for Property Graph databases only. Support for RDF has not yet been added.
+
+You can also **start with a GraphQL schema with your types and an empty Neptune database**. The utility will process your starting GraphQL schema and inference the directives required to map it to the Neptune database graph nodes and edges. You can also **start with a GraphQL schema with the directives**, that you have modified or created.
 
 The utility has the option to **generate the AWS resources** of the entire pipeline, including the AWS AppSync API, configuring the roles, data source, schema and resolver, and the AWS Lambda that queries Amazon Neptune.
 
@@ -85,7 +89,13 @@ To rollback, removing all the AWS resources run:
 <br>
 
 # Starting from a GraphQL schema and an empty Neptune database
-You can start from an empty Neptune database and use a GraphQL API to create the data and query it. Running the command below, the utility will automate the creation of the AWS resources. Your *your-graphql-schema-file* must include the GraphQL schema types, like in the TODO example [here](/doc/todoExample.md). The utility will analyze your schema and create an extended version based on your types. It will add queries and mutations for the nodes stored in the graph database, and in case your schema have nested types, it will add relationships between the types stored as edges in the graph database, again see the TODO example [here](/doc/todoExample.md). The utility creates an AppSync GraphQL API, and the required AWS resources, like a pair of IAM roles and a Lambda function with the GraphQL resolver code. As soon as the utility complete the execution, you will find in the AppSync console your new GraphQL API called *your-new-GraphQL-API-name*API. To test it, use the AppSync “Queries” from the menu. (*Note: follow the setup instructions below to enable your environment to reach the Neptune database and create AWS resources.*)
+You can start from an empty Neptune database and use a GraphQL API to create the data and query it. Running the command below, the utility will automate the creation of the AWS resources.
+Your *your-graphql-schema-file* must include the GraphQL schema types, like in the [TODO example](/doc/todoExample.md). The utility will analyze your schema and create an extended version based on your types. It will add queries and mutations for the nodes stored in the graph database, and in case your schema have nested types, it will add relationships between the types stored as edges in the graph database, again see the [TODO example](/doc/todoExample.md).
+The utility creates an AppSync GraphQL API and the required AWS resources, like a pair of IAM roles and a Lambda function with the GraphQL resolver code. As soon as the utility completes the execution, you will find in the AppSync console your new GraphQL API called *your-new-GraphQL-API-name*API. To test it, use the AppSync “Queries” from the menu.
+
+> [!TIP]
+>
+> Follow the setup instructions below to enable your environment to reach the Neptune database and create AWS resources.
 
 `neptune-for-graphql --input-schema-file `<*your-graphql-schema-file*>` --create-update-aws-pipeline --create-update-aws-pipeline-name` <*your-new-GraphQL-API-name*>` --create-update-aws-pipeline-neptune-endpoint` <*your-neptune-database-endpoint:port*>  ` --output-resolver-query-https`
 
@@ -106,7 +116,7 @@ You can start from a GraphQL schema with directives for a graph database. For th
 <br>
 
 # Customize the GraphQL schema with directives
-The utility generate a GraphQL schema with directives, queries and mutations. You might want to use it as is, or change it. Here below ways to change it.
+The utility generates a GraphQL schema with directives, queries and mutations. You might want to use it as is, or change it. Below are ways to change it.
 
 ### Please no mutations in my schema
 In case you don't want your Graph API having the option of updating your database data, add the the CLI option `--output-schema-no-mutations`.
@@ -141,15 +151,15 @@ type Airport @alias(property: "airport") {
 ### @graphQuery, @cypher
 You can define your openCypher queries to resolve a field value, add queries or mutations. 
 
-Here new a field *outboundRoutesCount* is added to the type *Airport* to count the outboud routes:
+Here a new field *outboundRoutesCount* is added to the type *Airport* to count the outbound routes:
 
 ```graphql
 type Airport @alias(property: "airport") {
   ...
   outboundRoutesCount: Int @graphQuery(statement: "MATCH (this)-[r:route]->(a) RETURN count(r)")
 }
 ```
-Here an example of new queries and mutations. Note that if you omit the *RETURN*, the resolver will assume the keyword *this* is the returning scope.
+Here is an example of new queries and mutations. Note that if you omit the *RETURN*, the resolver will assume the keyword *this* is the returning scope.
 ```graphql
 type Query {
   getAirportConnection(fromCode: String!, toCode: String!): Airport @cypher(statement: "MATCH (:airport{code: '$fromCode'})-[:route]->(this:airport)-[:route]->(:airport{code:'$toCode'})")   
@@ -171,7 +181,7 @@ type Query {
 ```
 
 ### @id
-The directive @id identify the field mapped to the graph database entity id. Graph databases like Amazon Neptune always have a unique id for nodes and edges assigned during bulk imports or autogenerated. 
+The directive @id identifies the field mapped to the graph database entity id. Graph databases like Amazon Neptune always have a unique id for nodes and edges assigned during bulk imports or autogenerated. 
 In the example below _id 
 ```graphql
 type Airport {
@@ -182,7 +192,7 @@ type Airport {
 ```
 
 ### Reserved types, queries and mutations names
-The utility autogenerates queries and mutations to enable you to have a working GraphQL API just after having ran the utility. The pattern of these names are recognized by the resolver and are reserved. Here an example for the type *Airport* and the connecting type *Route*:
+The utility auto generates queries and mutations to enable you to have a working GraphQL API just after having ran the utility. The pattern of these names are recognized by the resolver and are reserved. Here is an example for the type *Airport* and the connecting type *Route*:
 
 The type *Options* is reserved. 
 ```graphql
@@ -191,18 +201,18 @@ input Options {
 }
 ```
 
-The function parameters *filter*, and *options* are reserved.
+The function parameters *filter*, *options*, and *sort* are reserved.
 ```graphql
 type Query {  
-    getNodeAirports(filter: AirportInput, options: Options): [Airport]
+    getNodeAirports(filter: AirportInput, options: Options, sort: [AirportSort!]): [Airport]
 }
 ```
 
 The beginning of query names *getNode...*, and the beginning of the mutations names like *createNode...*, *updateNode...*, *deleteNode...*, *connectNode...*, *updateEdge...*, and *deleteEdge...*.
 ```graphql
 type Query {  
   getNodeAirport(id: ID, filter: AirportInput): Airport
-  getNodeAirports(filter: AirportInput): [Airport]
+  getNodeAirports(filter: AirportInput, options: Options, sort: [AirportSort!]): [Airport]
 }
 
 type Mutation {  
@@ -246,30 +256,30 @@ You have three option to created the GraphQL API pipeline:
 - You manually create the AWS resources 
 
 Independently of the method you or the utility will need to create the following resources:
-- Create a IAM role for Lambda called LambdaExecutionRole
+- Create an IAM role for Lambda called LambdaExecutionRole
 - Attach to the LambdaExecutionRole the IAM policy AWSLambdaBasicExecutionRole
 - For VPC (default) attach to the LambdaExecutionRole the IAM policy AWSLambdaVPCAccessExecutionRole
 - For IAM create and attach to the LambdaExecutionRole a new IAM policy that only allow to connect and query Neptune
 - Create a Lambda function with the LambdaExecutionRole
-- Create a IAM for AppSync API to call the Lambda called LambdaInvocationRole
+- Create an IAM for AppSync API to call the Lambda called LambdaInvocationRole
 - Attach to the LambdaInvocationRole the policy LambdaInvokePolicy
 - Create the AppSync GraphQL API 
 - Add to the AppSync API a Function with the LambdaInvocationRole to call the Lambda
 
 
 ### Let the utility create the resources
-With the CLI option `--create-update-aws-pipeline`, and its accesory options ([see the commands reference](https://github.com/aws/amazon-neptune-for-graphql/blob/main/doc/cliReference.md)), the utility automatically creates the resources.<br>
+With the CLI option `--create-update-aws-pipeline`, and its accessory options ([see the commands reference](https://github.com/aws/amazon-neptune-for-graphql/blob/main/doc/cliReference.md)), the utility automatically creates the resources.<br>
 You need to run the utility from a shell in which you installed the AWS CLI, and it is configured for a user with the permission of creating AWS resources. <br>
 The utility creates a file with the list of resources named *pipeline-name.resources.json*. Then it uses the file to modify the existing resources when the user runs the command again, or when the user wants to delete the AWS resources with the command option `--remove-aws-pipeline-name <value>`.
-The code of the utility uses the JavaScript AWS sdk v3, if you'd like to review the code is only in [this file](https://github.com/aws/amazon-neptune-for-graphql/blob/main/src/pipelineResources.js).
+The code of the utility uses the JavaScript AWS sdk v3, if you'd like to review the code, it is only in [this file](https://github.com/aws/amazon-neptune-for-graphql/blob/main/src/pipelineResources.js).
 
 ### I prefer a CDK file
-To option to trigger the creation of the CDK file starts with `--output-aws-pipeline-cdk`, and its accessory options ([see the commands reference](https://github.com/aws/amazon-neptune-for-graphql/blob/main/doc/cliReference.md)). <br> 
-After you ran it, you will find in the *output* folder the file *CDK-pipeline-name-cdk.js* and *CDK-pipeline-name.zip*. The ZIP file is the code for the Lambda function.
+The option to trigger the creation of the CDK file starts with `--output-aws-pipeline-cdk`, and its accessory options ([see the commands reference](https://github.com/aws/amazon-neptune-for-graphql/blob/main/doc/cliReference.md)). <br> 
+After running, you will find in the *output* folder the file *CDK-pipeline-name-cdk.js* and *CDK-pipeline-name.zip*. The ZIP file is the code for the Lambda function.
 See CDK end to end example [here](https://github.com/aws/amazon-neptune-for-graphql/blob/main/doc/cdk.md).
 
 ### Let me setup the resources manually or with my favorite DevOps toolchain
-[Here](https://github.com/aws/amazon-neptune-for-graphql/blob/main/doc/resources.md) the detailed list of resources needed to configure the GraphQL API pipeline.
+[Here](https://github.com/aws/amazon-neptune-for-graphql/blob/main/doc/resources.md) is the detailed list of resources needed to configure the GraphQL API pipeline.
 <br>
 
 # Generate Apollo Server Artifacts

doc/cdk.md

@@ -105,14 +105,14 @@ new AppSyncNeptuneStack(app, 'your-CdkStack-name', {
 
 ### Run the CDK application
 
-To create CloudFormantion template:
+To create CloudFormation template:
 
 `cdk synth`
 
 To deploy the CloudFormation template:
 
 `cdk deploy`
 
-To rollback your deployment:
+To roll back your deployment:
 
 `cdk destroy`