Improve docs

Author: anttiai

README.md

@@ -307,14 +307,14 @@ client.setThrottleTime(500);
 ```
 
 ## Indexing API
-The Indexing API allows for retrieving documents, creating documents, updating single documents and batches of 
-documents, as well as deleting single documents and batches of documents.
+With the Indexing API, you can fetch, create, update, and delete single documents or
+batches of documents.
 
-Following indexing API functions are meant to be used in Node.js. Never expose your
-secret key in your website code.
+Indexing API functions are meant to be used with Node.js. Never expose secret key in your 
+website code.
 
 ```js
-// Create client with your 32-character keys
+// Create client with your keys
 var client = new AddSearchClient('YOUR PUBLIC SITEKEY', 'YOUR SECRET KEY');
 ```
 
@@ -323,42 +323,25 @@ Always keep the key secret.
 
 All Indexing API functions are Promise-based.
 
+### Document structure
+Documents can contain a set of pre-defined fields, as well as any number of custom fields
+defined under the custom_fields key.
 
-### Document ID
-
-Document ID can be defined by the user, or it can be autogenerated when a document is added to the index.
-
-```js
-// ID defined by the user
-const docWithDefinedId = {
-  id: '1234',
-  custom_fields: {}
-}
-
-// ID created from the URL field (md5 sum)
-const docWithURL= {
-  url: 'https://..', // id will be md5('https://..')
-  custom_fields: {}
-}
-
-// ID will be generated automatically
-const docWithAutogeneratedId = {
-  // No id or url fields
-  custom_fields: {}
-}
-```
-
+Using pre-defined fields is optional, but default [Search UI](https://github.com/AddSearch/search-ui) components 
+display them by default, so they give you visible results faster.
 
-### Document structure
-Documents have schemaless data structures. Data fields should be defined under custom_fields key.
+Pre-defined fields are: url, title, h1, h2, language, title, main_content, and meta_description.
 
+Example document:
 ```js
-// Create client with your 32-character keys
 const doc = {
   id: '1234',
+  url: 'https://www.example-store.com/product-x',
+  title: 'Example product',
+  language: 'en',
   custom_fields: {
     'name': 'Example product',
-    'description': 'Description for example product',
+    'description': 'Description for the example product',
     'price_cents': 599,
     'average_customer_rating': 4.5,
     'release_date': 1589200255
@@ -374,9 +357,35 @@ Data types for custom fields are automatically detected from the content. Suppor
 
 Dates should be defined as UNIX timestamps with integer values.
 
+### Document ID
+
+If the id field is not defined in the document, it is generated automatically either randomly
+or from the URL field, when the document is added to the index.
+
+```js
+// ID defined by the user
+const docWithDefinedId = {
+  id: '1234',
+  custom_fields: {}
+}
+```
+```js
+// ID created from the URL field (md5 sum)
+const docWithURL= {
+  url: 'https://..', // id will be md5('https://..')
+  custom_fields: {}
+}
+```
+```js
+// ID generated randomly
+const docWithAutogeneratedId = {
+  // No id or url fields
+  custom_fields: {}
+}
+```
 
 ### Save document
-Add or update a document in the index.
+Add a document to the index, or update a document.
 
 ```js
 const doc = {
@@ -398,6 +407,7 @@ client.saveDocument(doc)
 
 
 ### Get document by ID
+Fetch a specific document by ID.
 ```js
 client.getDocument(id)
   .then(response => {
@@ -410,6 +420,7 @@ client.getDocument(id)
 
 
 ### Delete document by ID
+Delete a specific document by ID.
 ```js
 client.deleteDocument(id)
   .then(response => {
@@ -422,6 +433,7 @@ client.deleteDocument(id)
 
 
 ### Save batch of documents
+Add or update bunch of documents defined in an array.
 ```js
 const batch = {
   documents: [
@@ -452,6 +464,7 @@ client.saveDocumentsBatch(batch)
 
 
 ### Delete batch of documents
+Delete multiple documents with an array of document IDs.
 ```js
 // Array of document IDs
 const batch = {
@@ -469,7 +482,7 @@ client.deleteDocumentsBatch(batch)
 ```
 
 
-## Supported web browsers and node.js versions
+## Supported browsers
 The client is tested on
 - Chrome
 - Firefox