working on the documentation

README.md

@@ -4,25 +4,30 @@
 [![Code Coverage](https://scrutinizer-ci.com/g/Youshido/GraphQL/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/Youshido/GraphQL/?branch=master)
 [![SensioLabsInsight](https://insight.sensiolabs.com/projects/8b8ab2a2-32fb-4298-a986-b75ca523c7c9/mini.png)](https://insight.sensiolabs.com/projects/8b8ab2a2-32fb-4298-a986-b75ca523c7c9)
 
-This is a pure PHP realization of the GraphQL protocol based on the working draft of the specification located on https://github.com/facebook/graphql.
+This is a clean PHP realization of the GraphQL protocol based on the working draft of the specification located on https://github.com/facebook/graphql.
 
-GraphQL is a modern replacement of the REST API approach. It advanced in a lof ot ways and has fundamental advantages:
- - reusable API for different versions and devices
- - a complete new level of distinguishing the backend and the frontend logic
+GraphQL is a modern replacement of the REST API approach. It advanced in many ways and has fundamental improvements over the old not-so-good REST:
 
+ - self-checks embedded on the ground level of your app  
+ - reusable API for different client versions and devices – no need in "/v1" and "/v2" anymore 
+ - a complete new level of distinguishing the backend and the frontend logic
+ - easily generated documentation and incredibly easy way to explore API for other developers
+ - once your architecture is complete – simple changes on the client does not require you to change API
 
-Current package is and will be trying to keep up with the latest revision of the GraphQL specification which is of April 2016 currently.
+It could be hard to believe, but give it a try and you'll be rewarded with much better architecture and so much easier to support code. 
+
+_Current package is and will be trying to keep up with the latest revision of the GraphQL specification which is of April 2016 currently._
 
 ## Getting started
 
-You should be better off starting with some examples, and everybody's using Star Wars trilogy as a domain of knowledge in their examples.
+You should be better off starting with some examples, and "Star Wars" become a somewhat "Hello world" example for the GraphQL frameworks.
 We have that too and if you looking for just that – go directly by this link – [Star Wars example](https://github.com/Youshido/GraphQL/Tests/StarWars).
-On the other hand we believe it's easier to start with something more common so let's get started.
+On the other hand based on the feedback we prepared a step-by-step for those who want to get up to speed fast.
 
 ### Installation
 
 You should simply install this package using the composer. If you're not familiar with it you should check out the [manual](https://getcomposer.org/doc/00-intro.md).
-Add the following package to your `composer.json` and run `composer update`
+Add the following package to your `composer.json`:
 
  ```
  {
@@ -31,9 +36,11 @@ Add the following package to your `composer.json` and run `composer update`
      }
  }
  ```
+Run `composer update`.
 
-Let's check if everything is good by setting up a simple schema that will return current time.
-You can find this example in the examples directory – [01_sandbox](https://github.com/Youshido/GraphQL/examples/01_sandbox).
+After the successful message, Let's check if everything is good by setting up a simple schema that will return current time.
+(you can find this example in the examples directory – [01_sandbox](https://github.com/Youshido/GraphQL/examples/01_sandbox))
+
 ```php
 <?php
 namespace Sandbox;
@@ -62,7 +69,6 @@ $processor->setSchema(new Schema([
 
 $res = $processor->processRequest('{ currentTime }')->getResponseData();
 print_r($res);
-
 ```
 
 If everything was set up correctly – you should see response with your current time:
@@ -73,13 +79,14 @@ If everything was set up correctly – you should see response with your curren
  ```
 
 If not – check that you have the latest composer version and that you've created your test file in the same directory you have `vendor` folder in.
+You can always use a script from `examples` folder. Simply run `php vendor/youshido/GraphQL/examples/01_sandbox/index.php`.
 
 ## Usage
 
-Let's architect a schema for the simple Blog.
+Now, as an example, let's architect a schema for the Blog.
 
-We'll keep our Blog simple but it will surely have Users who write Posts and leave Comments.
-If you never seen a GraphQL queries before – it's a simple text query very much similar to the json/yaml format.
+We'll keep it simple but our Blog will surely have Users who write Posts and leave Comments.
+If you never seen a GraphQL queries before – it's a simple text query structured very much similar to the json/yaml format.
 Here's an example of the query that returns title and summary of the latest Post:
  ```
  latestPost {
@@ -88,7 +95,7 @@ Here's an example of the query that returns title and summary of the latest Post
  }
  ```
 
-Supposedly our server should return the following structure:
+Supposedly our server should reply with a response structured like following:
  ```
  {
     data: {
@@ -105,19 +112,36 @@ Now, let's create a schema and the backend that can handle this simple request.
 ### Creating Post schema
 
 We believe you'll be using our package along with your favorite framework (we have a Symfony version [here](http://github.com/Youshido/GraphqlBundle)).
-But for the purpose of the current demonstration we'll keep it as plain php code.
-
-*schema.php*
-```php
-
-
-
-```
-
-
+But for the purpose of the current example we'll keep it as plain php code.
+_(you can check out the complete example by the following link – (https://github.com/Youshido/GraphQL/examples/02_Blog)_
 
+We'll take a quick look on different approaches you can use to define your schema. Even though inline approach might seem to be easier and faster we strongly recommend to use an object based because it will give you more flexibility and freedom as your project grows.
 
+#### Inline approach
 
+So let's start by creating post type. For now we'll have only two fields – title and summary:
 
+*index.php*
+```php
+//...
+$rootQueryType = new ObjectType([
+    'name'   => 'RootQueryType',
+    'fields' => [
+        'latestPost' => new ObjectType([
+            'name'    => 'Post',
+            'fields'  => [
+                'title'   => new StringType(),
+                'summary' => new StringType(),
+            ],
+            'resolve' => function () {
+                return [
+                    "title"   => "New approach in API has been revealed",
+                    "summary" => "This post will describe a new approach to create and maintain APIs",
+                ];
+            }
+        ])
+    ]
+]);
+//...
+```
 
-

examples/Blog/index.php → examples/02_blog/index.php

@@ -10,14 +10,6 @@
     'name' => 'RootQueryType',
 ]);
 
-function resolvePost()
-{
-    return [
-        "title"   => "Interesting approach",
-        "summary" => "This new GraphQL library for PHP works really well",
-    ];
-}
-
 require_once __DIR__ . '/structures/object-inline.php';
 
 $processor = new Processor();