Merge branch 'johnbiundo-biundo/graphql-more-edits'

Author: kamilmysliwiec

content/graphql/quick-start.md

@@ -12,15 +12,15 @@ Start by installing the required packages:
 $ npm i --save @nestjs/graphql graphql-tools graphql
 ```
 
-And depending on what you use (Express or Fastify), you need to install `apollo-server-express` or `apollo-server-fastify`.
+Depending on what underlying platform you use (Express or Fastify), you must also install either `apollo-server-express` or `apollo-server-fastify`.
 
 #### Overview
 
-Nest offers two ways of building GraphQL applications, the **schema first** and the **code first** methods.
+Nest offers two ways of building GraphQL applications, the **code first** and the **schema first** methods. You should choose the one that works best for you. Most of the chapters in this GraphQL section are divided into two main parts: one you should follow if you adopt **code first**, and the other to be used if you adopt **schema first**.
 
 In the **code first** approach, you use decorators and TypeScript classes to generate the corresponding GraphQL schema. This approach is useful if you prefer to work exclusively with TypeScript and avoid context switching between language syntaxes.
 
-In the **schema first** approach, the source of truth is a GraphQL SDL (Schema Definition Language) SDL is a language-agnostic way to share schema files between different platforms. Nest automatically generates your TypeScript definitions based on the GraphQL schemas (using either classes or interfaces) to reduce redundancy.
+In the **schema first** approach, the source of truth is GraphQL SDL (Schema Definition Language) files. SDL is a language-agnostic way to share schema files between different platforms. Nest automatically generates your TypeScript definitions (using either classes or interfaces) based on the GraphQL schemas to reduce the need to write redundant boilerplate code.
 
 #### Getting started with GraphQL & TypeScript
 
@@ -36,7 +36,7 @@ import { GraphQLModule } from '@nestjs/graphql';
     GraphQLModule.forRoot({}),
   ],
 })
-export class ApplicationModule {}
+export class AppModule {}
 ```
 
 The `forRoot()` method takes an options object as an argument. These options are passed through to the underlying Apollo instance (read more about available settings [here](https://www.apollographql.com/docs/apollo-server/v2/api/apollo-server.html#constructor-options-lt-ApolloServer-gt)). For example, if you want to disable the `playground` and turn off `debug` mode, pass the following options:
@@ -54,16 +54,18 @@ import { GraphQLModule } from '@nestjs/graphql';
     }),
   ],
 })
-export class ApplicationModule {}
+export class AppModule {}
 ```
 
 As mentioned, these options will be forwarded to the `ApolloServer` constructor.
 
 <app-banner-enterprise></app-banner-enterprise>
 
-#### Playground
+#### GraphQL playground
 
-The playground is a graphical, interactive, in-browser GraphQL IDE, available by default on the same URL as the GraphQL server itself. With your application running in the background, open your web browser and navigate to `http://localhost:3000/graphql` (host and port may vary depending on your configuration). You should see the GraphQL playground, as shown below.
+The playground is a graphical, interactive, in-browser GraphQL IDE, available by default on the same URL as the GraphQL server itself. To access the playground, you need a basic GraphQL server configured and running. To see it now, you can install and build the [working example here](https://github.com/nestjs/nest/tree/master/sample/23-graphql-code-first). Alternatively, if you're following along with these code samples, once you've complete the steps in the [Resolvers chapter](/graphql/resolvers-map), you can access the playground.
+
+With that in place, and with your application running in the background, you can then open your web browser and navigate to `http://localhost:3000/graphql` (host and port may vary depending on your configuration). You will then see the GraphQL playground, as shown below.
 
 <figure>
   <img src="/assets/playground.png" alt="" />
@@ -83,11 +85,11 @@ GraphQLModule.forRoot({
 
 In the **code first** approach, you use decorators and TypeScript classes to generate the corresponding GraphQL schema.
 
-To use the code first approach, start by adding the `autoSchemaFile` property to the options object.
+To use the code first approach, start by adding the `autoSchemaFile` property to the options object:
 
 ```typescript
 GraphQLModule.forRoot({
-  autoSchemaFile: 'schema.gql',
+  autoSchemaFile: join(process.cwd(), 'src/schema.gql'),
 }),
 ```
 
@@ -99,21 +101,19 @@ GraphQLModule.forRoot({
 }),
 ```
 
-A fully working sample is available [here](https://github.com/nestjs/nest/tree/master/sample/23-graphql-code-first).
+A fully working code first sample is available [here](https://github.com/nestjs/nest/tree/master/sample/23-graphql-code-first).
 
 #### Schema first
 
-To use the schema first approach, start by adding a `typePaths` property to the options object.
+To use the schema first approach, start by adding a `typePaths` property to the options object. The `typePaths` property indicates where the `GraphQLModule` should look for GraphQL SDL schema definition files you'll be writing. These files will be combined in memory; this allows you to split your schemas into several files and locate them near their resolvers.
 
 ```typescript
 GraphQLModule.forRoot({
   typePaths: ['./**/*.graphql'],
 }),
 ```
 
-The `typePaths` property indicates where the `GraphQLModule` should look for GraphQL files. These files will be combined in memory; this allows you to split your schemas into several files and locate them near their resolvers.
-
-Creating GraphQL types and corresponding TypeScript definitions is redundant and tedious. It leaves us without a single source of truth -- each change made within SDL forces us to adjust interfaces as well. To address this, the `@nestjs/graphql` package can automatically generate TS definitions from the abstract syntax tree (AST). To enable this feature, add the `definitions` options property when configuring the `GraphQLModule`.
+You will typically also need to have TypeScript definitions (classes and interfaces) that correspond to the GraphQL SDL types. Creating the corresponding TypeScript definitions by hand is redundant and tedious. It leaves us without a single source of truth -- each change made within SDL forces us to adjust TypeScript definitions as well. To address this, the `@nestjs/graphql` package can **automatically generate** TypeScript definitions from the abstract syntax tree ([AST](https://en.wikipedia.org/wiki/Abstract_syntax_tree)). To enable this feature, add the `definitions` options property when configuring the `GraphQLModule`.
 
 ```typescript
 GraphQLModule.forRoot({
@@ -124,7 +124,7 @@ GraphQLModule.forRoot({
 }),
 ```
 
-The path property of the `definitions` object (e.g., `src/graphql.ts` above) indicates where to save TypeScript output. By default, all types are generated as interfaces. To generate classes instead, specify the `outputAs` property with a value of `'class'`.
+The path property of the `definitions` object indicates where to save generated TypeScript output. By default, all generated TypeScript types are created as interfaces. To generate classes instead, specify the `outputAs` property with a value of `'class'`.
 
 ```typescript
 GraphQLModule.forRoot({
@@ -136,7 +136,7 @@ GraphQLModule.forRoot({
 }),
 ```
 
-The above approach dynamically generates type definitions each time the application starts. Alternatively, it may be preferable to build a simple script to generate these on demand. For example, assume we create the following script as `generate-typings.ts`:
+The above approach dynamically generates TypeScript definitions each time the application starts. Alternatively, it may be preferable to build a simple script to generate these on demand. For example, assume we create the following script as `generate-typings.ts`:
 
 ```typescript
 import { GraphQLDefinitionsFactory } from '@nestjs/graphql';
@@ -150,7 +150,7 @@ definitionsFactory.generate({
 });
 ```
 
-Now you can run this script only when needed:
+Now you can run this script on demand:
 
 ```bash
 $ ts-node generate-typings
@@ -169,7 +169,7 @@ definitionsFactory.generate({
 });
 ```
 
-A fully working sample is available [here](https://github.com/nestjs/nest/tree/master/sample/12-graphql-schema-first).
+A fully working schema first sample is available [here](https://github.com/nestjs/nest/tree/master/sample/12-graphql-schema-first).
 
 #### Async configuration