Merge pull request #26 from ably/edx-155-blurb-clarifications

[EDX-155]: Update API reference blurb

README.md

@@ -73,13 +73,13 @@ The following text is an introduction that can be added to each static site gene
 ```
 # Ably `<Language>` Client Library SDK API Reference
 
-The `<Language>` Client Library SDK supports a realtime and a REST interface.
+The `<Language>` Client Library SDK supports a realtime and a REST interface. The `<Language>` API references are generated from the [Ably `<Language>` Client Library SDK source code](link-to-Ably-repo) using [`<Tool>`](link-to-tool) and structured by classes.
 
 The realtime interface enables a client to maintain a persistent connection to Ably and publish, subscribe and be present on channels. The REST interface is stateless and typically implemented server-side. It is used to make requests such as retrieving statistics, token authentication and publishing to a channel.
 
 **Note**: The `<Language>` Client Library SDK implements the realtime and REST interfaces as two separate libraries.
 
-The `<Language>` API references are generated from the [Ably `<Language>` Client Library SDK source code](link-to-Ably-repo) using [`<Tool>`](link-to-tool). View the [Ably docs](http://ably.com/docs/) for conceptual information on using Ably and for client library API references split between the [realtime](http://ably.com/docs/api/realtime-sdk) and [REST](http://ably.com/docs/api/rest-sdk) interfaces.
+View the [Ably docs](http://ably.com/docs/) for conceptual information on using Ably, and for API references featuring all languages. The combined API references are organized by features and split between the [realtime](http://ably.com/docs/api/realtime-sdk) and [REST](http://ably.com/docs/api/rest-sdk) interfaces.
 ```
 
 It can be amended as necessary, for example where an SDK implements the REST and realtime interfaces as two separate libraries.