Update READMEs and example docs (#609)

Scan through some of our documentation and update gramar and provide some more details where needed

Author: smyrick

README.md

@@ -1,27 +1,24 @@
 # GraphQL Kotlin
 
-[![Build Status](https://github.com/ExpediaGroup/graphql-kotlin/workflows/Continuous%20Integration/badge.svg)](https://expediagroup.github.io/graphql-kotlin)
+[![Build Status](https://github.com/ExpediaGroup/graphql-kotlin/workflows/Continuous%20Integration/badge.svg)](https://github.com/ExpediaGroup/graphql-kotlin/actions?query=workflow%3A%22Continuous+Integration%22)
+[![Docs](https://github.com/ExpediaGroup/graphql-kotlin/workflows/Publish%20Docs/badge.svg)](https://github.com/ExpediaGroup/graphql-kotlin/actions?query=workflow%3A%22Publish+Docs%22)
 [![codecov](https://codecov.io/gh/ExpediaGroup/graphql-kotlin/branch/master/graph/badge.svg)](https://codecov.io/gh/ExpediaGroup/graphql-kotlin)
-[![Docs](https://github.com/ExpediaGroup/graphql-kotlin/workflows/Publish%20Docs/badge.svg)](https://expediagroup.github.io/graphql-kotlin)
 [![Slack](https://img.shields.io/badge/Slack-%23graphql--kotlin-ECB22E.svg?logo=data:image/svg+xml;base64,PHN2ZyB2aWV3Qm94PSIwIDAgNTQgNTQiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PGcgZmlsbD0ibm9uZSIgZmlsbC1ydWxlPSJldmVub2RkIj48cGF0aCBkPSJNMTkuNzEyLjEzM2E1LjM4MSA1LjM4MSAwIDAgMC01LjM3NiA1LjM4NyA1LjM4MSA1LjM4MSAwIDAgMCA1LjM3NiA1LjM4Nmg1LjM3NlY1LjUyQTUuMzgxIDUuMzgxIDAgMCAwIDE5LjcxMi4xMzNtMCAxNC4zNjVINS4zNzZBNS4zODEgNS4zODEgMCAwIDAgMCAxOS44ODRhNS4zODEgNS4zODEgMCAwIDAgNS4zNzYgNS4zODdoMTQuMzM2YTUuMzgxIDUuMzgxIDAgMCAwIDUuMzc2LTUuMzg3IDUuMzgxIDUuMzgxIDAgMCAwLTUuMzc2LTUuMzg2IiBmaWxsPSIjMzZDNUYwIi8+PHBhdGggZD0iTTUzLjc2IDE5Ljg4NGE1LjM4MSA1LjM4MSAwIDAgMC01LjM3Ni01LjM4NiA1LjM4MSA1LjM4MSAwIDAgMC01LjM3NiA1LjM4NnY1LjM4N2g1LjM3NmE1LjM4MSA1LjM4MSAwIDAgMCA1LjM3Ni01LjM4N20tMTQuMzM2IDBWNS41MkE1LjM4MSA1LjM4MSAwIDAgMCAzNC4wNDguMTMzYTUuMzgxIDUuMzgxIDAgMCAwLTUuMzc2IDUuMzg3djE0LjM2NGE1LjM4MSA1LjM4MSAwIDAgMCA1LjM3NiA1LjM4NyA1LjM4MSA1LjM4MSAwIDAgMCA1LjM3Ni01LjM4NyIgZmlsbD0iIzJFQjY3RCIvPjxwYXRoIGQ9Ik0zNC4wNDggNTRhNS4zODEgNS4zODEgMCAwIDAgNS4zNzYtNS4zODcgNS4zODEgNS4zODEgMCAwIDAtNS4zNzYtNS4zODZoLTUuMzc2djUuMzg2QTUuMzgxIDUuMzgxIDAgMCAwIDM0LjA0OCA1NG0wLTE0LjM2NWgxNC4zMzZhNS4zODEgNS4zODEgMCAwIDAgNS4zNzYtNS4zODYgNS4zODEgNS4zODEgMCAwIDAtNS4zNzYtNS4zODdIMzQuMDQ4YTUuMzgxIDUuMzgxIDAgMCAwLTUuMzc2IDUuMzg3IDUuMzgxIDUuMzgxIDAgMCAwIDUuMzc2IDUuMzg2IiBmaWxsPSIjRUNCMjJFIi8+PHBhdGggZD0iTTAgMzQuMjQ5YTUuMzgxIDUuMzgxIDAgMCAwIDUuMzc2IDUuMzg2IDUuMzgxIDUuMzgxIDAgMCAwIDUuMzc2LTUuMzg2di01LjM4N0g1LjM3NkE1LjM4MSA1LjM4MSAwIDAgMCAwIDM0LjI1bTE0LjMzNi0uMDAxdjE0LjM2NEE1LjM4MSA1LjM4MSAwIDAgMCAxOS43MTIgNTRhNS4zODEgNS4zODEgMCAwIDAgNS4zNzYtNS4zODdWMzQuMjVhNS4zODEgNS4zODEgMCAwIDAtNS4zNzYtNS4zODcgNS4zODEgNS4zODEgMCAwIDAtNS4zNzYgNS4zODciIGZpbGw9IiNFMDFFNUEiLz48L2c+PC9zdmc+&labelColor=611f69)](https://kotlinlang.slack.com/messages/graphql-kotlin/)
-[![Awesome Kotlin Badge](https://kotlin.link/awesome-kotlin.svg)](https://github.com/KotlinBy/awesome-kotlin)
 
-GraphQL Kotlin consists of number of libraries that aim to simplify running a GraphQL server in Kotlin.
+GraphQL Kotlin is a collection of libraries built on top of [graphql-java](https://www.graphql-java.com/) that aim to simplify running a GraphQL server in Kotlin
 
 ## 📦 Modules
 
 * [graphql-kotlin-schema-generator](/graphql-kotlin-schema-generator) - Code only GraphQL schema generation for Kotlin
 * [graphql-kotlin-federation](/graphql-kotlin-federation) - Schema generator extension to build federated GraphQL schemas
-* [graphql-kotlin-spring-server](/graphql-kotlin-spring-server) - Spring Boot auto-configuration library to create GraphQL web app
+* [graphql-kotlin-spring-server](/graphql-kotlin-spring-server) - Spring Boot auto-configuration library to create a GraphQL web app
 * [examples](/examples) - Example apps that use graphql-kotlin libraries to test and demonstrate usages
 
 ## ⌨️ Usage
 
-Below is a basic example of how `graphql-kotlin-schema-generator` converts your Kotlin code into a GraphQL schema. For more details, see our documentation below or in the individual module READMEs
+Below is a basic example of how [graphql-kotlin-schema-generator](/graphql-kotlin-schema-generator) converts your Kotlin code into a GraphQL schema. For more details, see our documentation below or in the individual module READMEs
 
 ```kotlin
-// Your existing Kotlin code
-
 data class Widget(val id: Int, val value: String)
 
 class WidgetService {
@@ -31,7 +28,6 @@ class WidgetService {
 }
 
 // Generate the schema
-
 val config = SchemaGeneratorConfig(supportedPackages = listOf("org.example"))
 val queries = listOf(TopLevelObject(WidgetService()))
 
@@ -51,11 +47,30 @@ type Widget {
 }
 ```
 
+Then using [graphql-kotlin-spring-server](/graphql-kotlin-spring-server) you can easily make your schema available as a GraphQL server with Spring Boot.
+
+```kotlin
+// Mark the class as a Spring GraphQL Query
+@Component
+class WidgetService : Query {
+  fun widgetById(id: Int): Widget? {}
+}
+
+@SpringBootApplication
+class Application
+
+fun main(args: Array<String>) {
+    runApplication<Application>(*args)
+}
+```
+
 ## 📋 Documentation
 
-Examples and documentation are available on our [documentation](https://expediagroup.github.io/graphql-kotlin), or in each module README file.
+Examples and documentation are available on our [documentation site](https://expediagroup.github.io/graphql-kotlin) hosted in GitHub Pages.
+
+If you have a question about something you can not find in our documentation, the indivdual module READMEs, or [javadocs](https://www.javadoc.io/doc/com.expediagroup/graphql-kotlin-schema-generator), feel free to [create an issue](https://github.com/ExpediaGroup/graphql-kotlin/issues) and tag it with the question label.
 
-If you have a question about something you can not find in our documentation, the indivdual modules, or javadocs, feel free to [create an issue](https://github.com/ExpediaGroup/graphql-kotlin/issues) and tag it with the question label.
+If you would like to contribute to our documentation see the [website](/website) directory for more information.
 
 ## 👥 Contact
 

examples/README.md

@@ -2,5 +2,5 @@
 
 Example apps that use `graphql-kotlin` libraries to test and demonstrate usages.
 
-* [spring](https://github.com/ExpediaGroup/graphql-kotlin/tree/master/examples/spring) - This is a sample Spring Boot app that uses `graphql-kotlin-spring-server` to create reactive GraphQL web application. Please refer to the README file for details on how to run the target application.
-* [federation](https://github.com/ExpediaGroup/graphql-kotlin/tree/master/examples/federation) - Example Spring Boot apps generating Federated GraphQL schema and Apollo Gateway that exposes single federated schema are provided in examples/federation project. Please refer to their README files for details on how to run the target applications.
+* [spring](https://github.com/ExpediaGroup/graphql-kotlin/tree/master/examples/spring) - This is a sample Spring Boot app that uses `graphql-kotlin-spring-server` to create a reactive GraphQL web application. Please refer to the README file for details on how to run the application.
+* [federation](https://github.com/ExpediaGroup/graphql-kotlin/tree/master/examples/federation) - Example Spring Boot apps generating federated GraphQL schemas and an Apollo Gateway in NodeJS that exposes the merged federated schema. Please refer to the README files for details on how to run each federated service.

examples/federation/README.md

@@ -1,21 +1,23 @@
 # Federation Example
 
 This example is two Spring applications `base-app` and `extend-app` that use `graphql-kotlin-federation` to generate the schema.
-These apps run on different ports (`8080`, `8081`) so they can run simultaniously
+These apps run on different ports (`8080`, `8081`) so they can run simultaniously.
 
-Then the `gateway` is a Node.js app running Apollo Gateway on port `4000` and connects to the two spring apps.
-You can make queries against the spring apps directly or combined queries from the gateway.
+The `gateway` is a Node.js app running Apollo Gateway on port `4000` and connects to the two Spring apps.
+You can make queries against the Spring apps directly or run combined queries from the gateway.
 
 ## Running Locally
 
 
 ### Spring Apps
-Build the spring applications by running the following commands in the `/federation` directory
+Build the Spring applications by running the following commands in the `/federation` directory
 
 ```shell script
 ./gradlew clean build
 ```
 
+> NOTE: in order to ensure you use the right version of Gradle we highly recommend to use the provided wrapper scripts
+
 Start the servers:
 
 * Run each `Application.kt` directly from your IDE
@@ -26,10 +28,10 @@ Start the servers:
 ```
 
 
-Once the app has started you can explore the example schema by opening Playground endpoint
+Once the app has started you can explore the example schema by opening the Playground endpoint
 * `base-app` http://localhost:8080/playground
 * `extend-app` http://localhost:8081/playground
 
 ### Gateway
 
-See the instructions in the [README](./gateway/README.md) for this folder
+See the instructions in the gateway [README](./gateway/README.md)

examples/federation/gateway/.gitignore

@@ -3,5 +3,5 @@
 /node_modules
 /build
 /logs
-
 *.log
+yarn.lock

examples/federation/gateway/.nvmrc

@@ -1 +1 @@
-12.9.1
+12

examples/federation/gateway/README.md

@@ -1,19 +1,19 @@
 # Apollo Federation
 
-This is a simple Apollo Federation Gateway. For more info see the Apollo docs
+This is a simple Apollo Federation Gateway server. For more info see the Apollo docs
 
 https://www.apollographql.com/docs/apollo-server/federation/introduction/
 
 ## Setup
 
-Install the correct version of Node and have yarn installed locally
+Install the correct version of Node locally. You can also use [nvm](https://github.com/nvm-sh/nvm)
 
 ```shell script
 nvm i
 ```
 
 ```shell script
-yarn install
+npm install
 ```
 
 Then start the other applications
@@ -23,5 +23,5 @@ Then start the other applications
 
 Then you can start the gateway
 ```shell script
-yarn start
+npm start
 ```

examples/federation/gateway/index.js

@@ -15,7 +15,7 @@
  */
 
 const { ApolloServer } = require("apollo-server");
-const { ApolloGateway, RemoteGraphQLDataSource } = require("@apollo/gateway");
+const { ApolloGateway } = require("@apollo/gateway");
 
 const server = new ApolloServer({
   gateway: new ApolloGateway({