Tweak the documentation after review

Author: pyrech

README.md

@@ -1,6 +1,4 @@
-# Introduction
-
-This library is a **PHP client** for **Slack's Web API**.
+# A PHP client for Slack's API
 
 There is a bunch of existing PHP clients for Slack. But some are not up to date
 or miss features, some only cover a small part of the API and most are simply
@@ -40,6 +38,8 @@ $client = JoliCode\Slack\ClientFactory::create($yourSlackToken);
 $user = $client->usersInfo(['user' => 'U123AZER'])->getUser();
 ```
 
+## Documentation
+
 Want more documentation or examples? See the [full documentation here](https://jolicode.github.io/slack-php-api/).
 
 ## Further documentation

docs/1-get-started.md

@@ -19,6 +19,13 @@ You can now install the Slack client:
 composer require jolicode/slack-php-api
 ```
 
+## Slack token
+
+Before you can use this client, you need to retrieve a token from Slack.
+
+Checkout Slack's documentation about [all different kind of tokens](https://api.slack.com/authentication/token-types).
+A good starting point is the [Authentication Basics documentation](https://api.slack.com/authentication/basics).
+
 ## Quick start
 
 ```php

docs/2-usage.md

@@ -1,12 +1,5 @@
 # Usage
 
-## Slack token
-
-Before you can use this client, you need to retrieve a token from Slack.
-
-Checkout Slack's documentation about [all different kind of tokens](https://api.slack.com/authentication/token-types).
-A good starting point is the [Authentication Basics documentation](https://api.slack.com/authentication/basics).
-
 ## Basic usage of the client
 
 Use the `ClientFactory` to generate a `Client` configured with your token:
@@ -28,9 +21,23 @@ PHPdoc to know which option you can provide to each method:
 <?php
 //...
 
-$members = $client->usersList(['limit' => 100])->getMembers();
+$user = $client->usersInfo(['user' => 'U123AZER'])->getUser();
+
+dump($user);
 ```
 
+Here is what a User object looks like:
+
+<p align="center">
+  <img src="images/model-sample.png" alt="Sample user object" />
+<p>
+
+To summarize - the whole SDK is built with objects. Each endpoints, responses
+and models have their own PHP classes with correct typehinting and PHPDoc.
+
+Along with [official Slack documentation](https://api.slack.com/methods), your
+favorite PHP editor should be a good ally to explore the whole API.
+
 ## Iterating over pagination
 
 Some Slack API endpoints use a cursor based pagination.