Work in progress on better docs

docs/best-practices.md

@@ -9,7 +9,7 @@ To enable validation - call: `GraphQL\Type\Definition\Config::enableValidation()
 but make sure to restrict it to debug/development mode only.
 
 # Type Registry
-**graphql-php** expects that each type in Schema is presented with single instance. Therefore
+**graphql-php** expects that each type in Schema is presented by single instance. Therefore
 if you define your types as separate PHP classes you need to ensure that each type is referenced only once.
  
 Technically you can create several instances of your type (for example for tests), but `GraphQL\Schema` 

docs/error-handling.md

@@ -126,12 +126,15 @@ try {
         // ...
     ]);
     
-    $result = GraphQL::execute($schema, $query);
+    $body = GraphQL::execute($schema, $query);
+    $status = 200;
 } catch(\Exception $e) {
-    header('Content-Type: application/json', true, 500);
-    echo json_encode([
+    $body = json_encode([
         'message' => 'Unexpected error'
     ]);
-    exit;
+    $status = 500;
 }
+
+header('Content-Type: application/json', true, $status);
+echo json_encode($body);
 ```

docs/getting-started.md

@@ -15,9 +15,11 @@ add `composer.json` file to your project root folder with following contents:
 ```
 and run `composer install`. 
 
-If you already have composer.json file - simply run: `composer require webonyx/graphql-php`
+If you already have composer.json file - simply run: `composer require webonyx/graphql-php="^0.7"`
 
-If you are upgrading, see [upgrade instructions](https://github.com/webonyx/graphql-php/blob/master/UPGRADE.md)
+# Upgrading
+We try to keep library releases backwards compatible. But when breaking changes are inevitable 
+they are explained in [upgrade instructions](https://github.com/webonyx/graphql-php/blob/master/UPGRADE.md).
 
 # Install Tools (optional)
 While it is possible to communicate with GraphQL API using regular HTTP tools it is way 
@@ -68,7 +70,7 @@ $queryType = new ObjectType([
 ```
 
 (Note: type definition can be expressed in [different styles](type-system/#type-definition-styles), 
-including **inheritance**, **composition** and **inline**. This example uses **inline** style for simplicity)
+but this example uses **inline** style for simplicity)
 
 The interesting piece here is `resolve` option of field definition. It is responsible for retuning 
 value of our field. Values of **scalar** fields will be directly included in response while values of 

docs/type-system/enum-types.md

@@ -28,8 +28,8 @@ $episodeEnum = new EnumType([
 ]);
 ```
 
-This example uses **inline** style for Enum Type definition, but there are also 
-[other styles](/type-system/#type-definition-styles) (using inheritance or composition).
+This example uses **inline** style for Enum Type definition, but you can also use
+[inheritance](/type-system/#type-definition-styles).
 
 # Configuration options
 Enum Type constructor accepts array with following options:

docs/type-system/index.md

@@ -79,7 +79,7 @@ class BlogPostType extends ObjectType
 ```
 
 # Type Registry
-Every type must be presented in Schema with single instance (**graphql-php** 
+Every type must be presented in Schema by single instance (**graphql-php** 
 throws when it discovers several instances with the same `name` in schema).
 
 Therefore if you define your type as separate PHP class you must ensure that only one 

docs/type-system/interfaces.md

@@ -31,8 +31,8 @@ $character = new InterfaceType([
     }
 ]);
 ```
-This example uses **inline** style for Interface definition, but there are also 
-[other styles](/type-system/#type-definition-styles) (using inheritance or composition).
+This example uses **inline** style for Interface definition, but you can also use  
+[inheritance](/type-system/#type-definition-styles).
 
 # Configuration options
 Constructor of InterfaceType accepts an array. Below is a full list of allowed options:

docs/type-system/object-types.md

@@ -56,8 +56,8 @@ $blogStory = new ObjectType([
     ]
 ]);
 ```
-This example uses **inline** style for Object Type definitions, but there are also 
-[other styles](/type-system/#type-definition-styles) (using inheritance or composition).
+This example uses **inline** style for Object Type definitions, but you can also use  
+[inheritance](/type-system/#type-definition-styles).
 
 
 # Configuration options

docs/type-system/unions.md

@@ -22,8 +22,8 @@ $searchResultType = new UnionType([
 ]);
 ```
 
-This example uses **inline** style for Union definition, but there are also 
-[other styles](/type-system/#type-definition-styles) (using inheritance or composition).
+This example uses **inline** style for Union definition, but you can also use  
+[inheritance](/type-system/#type-definition-styles).
 
 # Configuration options
 Constructor of UnionType accepts an array. Below is a full list of allowed options:

mkdocs.yml

@@ -15,7 +15,7 @@ pages:
   - Schema: type-system/schema.md
 - Executing Queries: executing-queries.md
 - Handling Errors: error-handling.md
-- Fetching Data: data-fetching.md
-- Best Practices: best-practices.md
+# - Fetching Data: data-fetching.md
+# - Best Practices: best-practices.md
 - Complementary Tools: complementary-tools.md
 theme: readthedocs