diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index 4eb5d2b615..c81f0a663d 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -13,11 +13,11 @@
 
 ## Examples
 
-- [Overview](examples/README.md)
-- [Simple connect](examples/01_simple_connect/README.md)
-- [Listen to blocks](examples/02_listen_to_blocks/README.md)
-- [Listen to balance change](examples/03_listen_to_balance_change/README.md)
-- [Generate Accounts](examples/04_generate_account/README.md)
-- [Read Storage](examples/05_read_storage/README.md)
-- [Craft Extrinsic](examples/06_craft_extrinsic/README.md)
-- [Transfer DOTs](examples/07_transfer_dots/README.md)
+- [RPC](examples-rpc/README.md)
+  - [Simple connect](examples-rpc/01_simple_connect/README.md)
+  - [Listen to blocks](examples-rpc/02_listen_to_blocks/README.md)
+  - [Listen to balance change](examples-rpc/03_listen_to_balance_change/README.md)
+  - [Generate Accounts](examples-rpc/04_generate_account/README.md)
+  - [Read Storage](examples-rpc/05_read_storage/README.md)
+  - [Craft Extrinsic](examples-rpc/06_craft_extrinsic/README.md)
+  - [Transfer DOTs](examples-rpc/07_transfer_dots/README.md)
diff --git a/docs/examples/.gitignore b/docs/examples-rpc/.gitignore
similarity index 100%
rename from docs/examples/.gitignore
rename to docs/examples-rpc/.gitignore
diff --git a/docs/examples/01_simple_connect/README.md b/docs/examples-rpc/01_simple_connect/README.md
similarity index 100%
rename from docs/examples/01_simple_connect/README.md
rename to docs/examples-rpc/01_simple_connect/README.md
diff --git a/docs/examples/01_simple_connect/index.html b/docs/examples-rpc/01_simple_connect/index.html
similarity index 100%
rename from docs/examples/01_simple_connect/index.html
rename to docs/examples-rpc/01_simple_connect/index.html
diff --git a/docs/examples/01_simple_connect/index.js b/docs/examples-rpc/01_simple_connect/index.js
similarity index 100%
rename from docs/examples/01_simple_connect/index.js
rename to docs/examples-rpc/01_simple_connect/index.js
diff --git a/docs/examples/01_simple_connect/package.json b/docs/examples-rpc/01_simple_connect/package.json
similarity index 100%
rename from docs/examples/01_simple_connect/package.json
rename to docs/examples-rpc/01_simple_connect/package.json
diff --git a/docs/examples/02_listen_to_blocks/README.md b/docs/examples-rpc/02_listen_to_blocks/README.md
similarity index 100%
rename from docs/examples/02_listen_to_blocks/README.md
rename to docs/examples-rpc/02_listen_to_blocks/README.md
diff --git a/docs/examples/02_listen_to_blocks/index.html b/docs/examples-rpc/02_listen_to_blocks/index.html
similarity index 100%
rename from docs/examples/02_listen_to_blocks/index.html
rename to docs/examples-rpc/02_listen_to_blocks/index.html
diff --git a/docs/examples/02_listen_to_blocks/index.js b/docs/examples-rpc/02_listen_to_blocks/index.js
similarity index 100%
rename from docs/examples/02_listen_to_blocks/index.js
rename to docs/examples-rpc/02_listen_to_blocks/index.js
diff --git a/docs/examples/02_listen_to_blocks/package.json b/docs/examples-rpc/02_listen_to_blocks/package.json
similarity index 100%
rename from docs/examples/02_listen_to_blocks/package.json
rename to docs/examples-rpc/02_listen_to_blocks/package.json
diff --git a/docs/examples/03_listen_to_balance_change/README.md b/docs/examples-rpc/03_listen_to_balance_change/README.md
similarity index 100%
rename from docs/examples/03_listen_to_balance_change/README.md
rename to docs/examples-rpc/03_listen_to_balance_change/README.md
diff --git a/docs/examples/03_listen_to_balance_change/index.html b/docs/examples-rpc/03_listen_to_balance_change/index.html
similarity index 100%
rename from docs/examples/03_listen_to_balance_change/index.html
rename to docs/examples-rpc/03_listen_to_balance_change/index.html
diff --git a/docs/examples/03_listen_to_balance_change/index.js b/docs/examples-rpc/03_listen_to_balance_change/index.js
similarity index 100%
rename from docs/examples/03_listen_to_balance_change/index.js
rename to docs/examples-rpc/03_listen_to_balance_change/index.js
diff --git a/docs/examples/03_listen_to_balance_change/package.json b/docs/examples-rpc/03_listen_to_balance_change/package.json
similarity index 100%
rename from docs/examples/03_listen_to_balance_change/package.json
rename to docs/examples-rpc/03_listen_to_balance_change/package.json
diff --git a/docs/examples/04_generate_account/README.md b/docs/examples-rpc/04_generate_account/README.md
similarity index 100%
rename from docs/examples/04_generate_account/README.md
rename to docs/examples-rpc/04_generate_account/README.md
diff --git a/docs/examples/04_generate_account/index.html b/docs/examples-rpc/04_generate_account/index.html
similarity index 100%
rename from docs/examples/04_generate_account/index.html
rename to docs/examples-rpc/04_generate_account/index.html
diff --git a/docs/examples/04_generate_account/index.js b/docs/examples-rpc/04_generate_account/index.js
similarity index 100%
rename from docs/examples/04_generate_account/index.js
rename to docs/examples-rpc/04_generate_account/index.js
diff --git a/docs/examples/04_generate_account/package.json b/docs/examples-rpc/04_generate_account/package.json
similarity index 100%
rename from docs/examples/04_generate_account/package.json
rename to docs/examples-rpc/04_generate_account/package.json
diff --git a/docs/examples/05_read_storage/README.md b/docs/examples-rpc/05_read_storage/README.md
similarity index 100%
rename from docs/examples/05_read_storage/README.md
rename to docs/examples-rpc/05_read_storage/README.md
diff --git a/docs/examples/05_read_storage/index.html b/docs/examples-rpc/05_read_storage/index.html
similarity index 100%
rename from docs/examples/05_read_storage/index.html
rename to docs/examples-rpc/05_read_storage/index.html
diff --git a/docs/examples/05_read_storage/index.js b/docs/examples-rpc/05_read_storage/index.js
similarity index 100%
rename from docs/examples/05_read_storage/index.js
rename to docs/examples-rpc/05_read_storage/index.js
diff --git a/docs/examples/05_read_storage/package.json b/docs/examples-rpc/05_read_storage/package.json
similarity index 100%
rename from docs/examples/05_read_storage/package.json
rename to docs/examples-rpc/05_read_storage/package.json
diff --git a/docs/examples/06_craft_extrinsic/README.md b/docs/examples-rpc/06_craft_extrinsic/README.md
similarity index 100%
rename from docs/examples/06_craft_extrinsic/README.md
rename to docs/examples-rpc/06_craft_extrinsic/README.md
diff --git a/docs/examples/06_craft_extrinsic/index.html b/docs/examples-rpc/06_craft_extrinsic/index.html
similarity index 100%
rename from docs/examples/06_craft_extrinsic/index.html
rename to docs/examples-rpc/06_craft_extrinsic/index.html
diff --git a/docs/examples/06_craft_extrinsic/index.js b/docs/examples-rpc/06_craft_extrinsic/index.js
similarity index 100%
rename from docs/examples/06_craft_extrinsic/index.js
rename to docs/examples-rpc/06_craft_extrinsic/index.js
diff --git a/docs/examples/06_craft_extrinsic/package.json b/docs/examples-rpc/06_craft_extrinsic/package.json
similarity index 100%
rename from docs/examples/06_craft_extrinsic/package.json
rename to docs/examples-rpc/06_craft_extrinsic/package.json
diff --git a/docs/examples/07_transfer_dots/README.md b/docs/examples-rpc/07_transfer_dots/README.md
similarity index 100%
rename from docs/examples/07_transfer_dots/README.md
rename to docs/examples-rpc/07_transfer_dots/README.md
diff --git a/docs/examples/07_transfer_dots/index.html b/docs/examples-rpc/07_transfer_dots/index.html
similarity index 100%
rename from docs/examples/07_transfer_dots/index.html
rename to docs/examples-rpc/07_transfer_dots/index.html
diff --git a/docs/examples/07_transfer_dots/index.js b/docs/examples-rpc/07_transfer_dots/index.js
similarity index 100%
rename from docs/examples/07_transfer_dots/index.js
rename to docs/examples-rpc/07_transfer_dots/index.js
diff --git a/docs/examples/07_transfer_dots/package.json b/docs/examples-rpc/07_transfer_dots/package.json
similarity index 100%
rename from docs/examples/07_transfer_dots/package.json
rename to docs/examples-rpc/07_transfer_dots/package.json
diff --git a/docs/examples/README.md b/docs/examples-rpc/README.md
similarity index 100%
rename from docs/examples/README.md
rename to docs/examples-rpc/README.md
diff --git a/docs/examples/index.html b/docs/examples-rpc/index.html
similarity index 100%
rename from docs/examples/index.html
rename to docs/examples-rpc/index.html
diff --git a/packages/api-observable/README.md b/packages/api-observable/README.md
index 4c9456a201..be31559c47 100644
--- a/packages/api-observable/README.md
+++ b/packages/api-observable/README.md
@@ -1,13 +1,3 @@
-[![polkadotjs](https://img.shields.io/badge/polkadot-js-orange.svg?style=flat-square)](https://polkadot.js.org)
-![isc](https://img.shields.io/badge/license-ISC-lightgrey.svg?style=flat-square)
-[![style](https://img.shields.io/badge/code%20style-semistandard-lightgrey.svg?style=flat-square)](https://github.com/Flet/semistandard)
-[![npm](https://img.shields.io/npm/v/@polkadot/api-observable.svg?style=flat-square)](https://www.npmjs.com/package/@polkadot/api-observable)
-[![travis](https://img.shields.io/travis/polkadot-js/api.svg?style=flat-square)](https://travis-ci.org/polkadot-js/api)
-[![maintainability](https://img.shields.io/codeclimate/maintainability/polkadot-js/api.svg?style=flat-square)](https://codeclimate.com/github/polkadot-js/api/maintainability)
-[![coverage](https://img.shields.io/coveralls/polkadot-js/api.svg?style=flat-square)](https://coveralls.io/github/polkadot-js/api?branch=master)
-[![dependency](https://david-dm.org/polkadot-js/api.svg?style=flat-square&path=packages/api-observable)](https://david-dm.org/polkadot-js/api?path=packages/api-observable)
-[![devDependency](https://david-dm.org/polkadot-js/api/dev-status.svg?style=flat-square&path=packages/api-observable)](https://david-dm.org/polkadot-js/api?path=packages/api-observable#info=devDependencies)
-
 # @polkadot/api
 
 An Observable wrapper around [@polkadot/rpc-core](../rpc-core).
diff --git a/packages/api/README.md b/packages/api/README.md
index 448f9f6680..6ab3aef0eb 100644
--- a/packages/api/README.md
+++ b/packages/api/README.md
@@ -1,18 +1,23 @@
-[![polkadotjs](https://img.shields.io/badge/polkadot-js-orange.svg?style=flat-square)](https://polkadot.js.org)
-![isc](https://img.shields.io/badge/license-ISC-lightgrey.svg?style=flat-square)
-[![style](https://img.shields.io/badge/code%20style-semistandard-lightgrey.svg?style=flat-square)](https://github.com/Flet/semistandard)
-[![npm](https://img.shields.io/npm/v/@polkadot/api.svg?style=flat-square)](https://www.npmjs.com/package/@polkadot/api)
-[![travis](https://img.shields.io/travis/polkadot-js/api.svg?style=flat-square)](https://travis-ci.org/polkadot-js/api)
-[![maintainability](https://img.shields.io/codeclimate/maintainability/polkadot-js/api.svg?style=flat-square)](https://codeclimate.com/github/polkadot-js/api/maintainability)
-[![coverage](https://img.shields.io/coveralls/polkadot-js/api.svg?style=flat-square)](https://coveralls.io/github/polkadot-js/api?branch=master)
-[![dependency](https://david-dm.org/polkadot-js/api.svg?style=flat-square&path=packages/api)](https://david-dm.org/polkadot-js/api?path=packages/api)
-[![devDependency](https://david-dm.org/polkadot-js/api/dev-status.svg?style=flat-square&path=packages/api)](https://david-dm.org/polkadot-js/api?path=packages/api#info=devDependencies)
-
 # @polkadot/api
 
-An RxJs wrapper around [@polkadot/rpc-core](../rpc-core).
+The Polkadot-JS API provides easy-to-use wrappers around JSONRPC calls that flow from an application to a node. It handles all the encoding and decoding or parameters, provides access to RPC functions and allows for the query of chain state and the submission of transactions.
 
-# Usage
+The API wrappers provide a standard interface for use -
+
+- A static `.create(<optional WsProvider>)` that returns an API istance when connected, decorated and ready-to use
+- The above is just a wrapper for `new Api(<optional WsProvider>) `, exposing the `isReady` getter
+- `api.rpc.*` provides access to actual RPC calls, be it for queries, submission or retrieving chain information
+- `api.st.*` provides access to chain state queries. These are dynamically populated based on what the runtime provides
+- `api.tx.*` provides the ability to create transaction, like chain state, this list is populated from a runtime query
+
+## API Selection
+
+There are two flavours of the API provided, one allowing a standard interface via JavaScript Promises and the second provides an Observable wrapper using [RxJS](https://github.com/ReactiveX/rxjs). Depending on your use-case and familiarity, you can choose either (or even both) for your application.
+
+- [ApiPromise](promise/) All interface calls returns Promises, including the static `.create(...)`. Additionally any subscription method use standard JavaScript `(error, value) => {}` callbacks.
+- [ApiRx](rx/) All interface calls return RxJS Observables, including the static `.create(...)`. In the same fashion and subscription-based methods return long-running Observables that update with the latest values.
+
+## Installation & import
 
 Installation -
 
@@ -20,14 +25,26 @@ Installation -
 npm install --save @polkadot/api/rx
 ```
 
-Making rpc calls -
+Subscribing to blocks via Promise-based API -
 
 ```javascript
-import ApiRx from '@polkadot/api/rx';
-// alternatively
-// import { ApiRx } from '@polkadot/api';
+import { ApiPromise } from '@polkadot/api';
 
-// initialise via Promise & static create
+// initialise via static create
+const api = await ApiPromise.create();
+
+// make a call to retrieve the current network head
+api.rpc.chain.newHead((error, header) => {
+  console.log(`Chain is at #${header.blockNumber}`);
+});
+```
+
+Subscribing to blocks via RxJS-based API -
+
+```javascript
+import { ApiRx } from '@polkadot/api';
+
+// initialise via static create
 const api = await ApiRx.create().toPromise();
 
 // make a call to retrieve the current network head
@@ -36,16 +53,9 @@ api.rpc.chain.newHead().subscribe((header) => {
 });
 ```
 
-Subscribing to chain state -
+## Users
 
-```javascript
-import Api from '@polkadot/api';
+Some of the users of the API (let us know if you are missing from the list), include -
 
-// initialise via isReady & new
-new Api().isReady.subscribe((api) => {
-  // make a call to retrieve the current network head
-  api.st.timestamp.now().subscribe((timestamp) => {
-    console.log(`Current block timestamp ${timestamp}`);
-  });
-});
-```
+- [Polkadot-JS UI](https://github.com/polkadot-js/apps) A user-interface that allows you to make transactions, query the network or participate in actions on the network such as referendums and staking
+- [Polkabot](https://gitlab.com/Polkabot) Polkabot is a Matrix chatbot that keeps an eye on the Polkadot network. You can see Polkabot in action in https://matrix.to/#/#polkadot-network-status:matrix.org
diff --git a/packages/api/src/promise/index.ts b/packages/api/src/promise/index.ts
index 6a6c12ab4c..dbf3c4e4c3 100644
--- a/packages/api/src/promise/index.ts
+++ b/packages/api/src/promise/index.ts
@@ -9,11 +9,86 @@ import Rpc from '@polkadot/rpc-core/index';
 import { Extrinsics, ExtrinsicFunction } from '@polkadot/extrinsics/types';
 import { Storage } from '@polkadot/storage/types';
 import { Base } from '@polkadot/types/codec';
+import isFunction from '@polkadot/util/is/function';
 
 import ApiBase from '../Base';
 import SubmittableExtrinsic from './SubmittableExtrinsic';
 import { StorageFunction } from '@polkadot/types/StorageKey';
 
+/**
+ * @description
+ * ApiPromise is a standard JavaScript wrapper around the RPC and interfaces on the Polkadot network. As a full Promise-based, all interface calls return Promises, including the static `.create(...)`. Subscription calls utilise standard JavaScript-convention `(error, value)` callbacks.
+ *
+ * The API is well suited to real-time applications where either the single-shot state is needed or use is to be made of  athe subscription-based features of Polkadot (and Substrate) clients.
+ *
+ * @example
+ * <BR>
+ *
+ * Making rpc calls -
+ * <BR>
+ *
+ * ```javascript
+ * import ApiPromise from '@polkadot/api/promise';
+ *
+ * // initialise via static create
+ * const api = await ApiPromise.create();
+ *
+ * // make a subscription to the network head
+ * api.rpc.chain.newHead((error, header) => {
+ *   console.log(`Chain is at #${header.blockNumber}`);
+ * });
+ * ```
+ * <BR>
+ *
+ * Subscribing to chain state -
+ * <BR>
+ *
+ * ```javascript
+ * import { ApiPromise } from '@polkadot/api';
+ * import WsProvider from '@polkadot/rpc-provider/ws';
+ *
+ * // initialise via isReady & new with specific non-local endpoint
+ * const api = await new ApiPromise(new WsProvider('wss://example.com:9944')).isReady;
+ *
+ * // retrieve the block target time
+ * const blockPeriod = await api.st.timestamp.blockPeriod().toNumber();
+ * let last = 0;
+ *
+ * // subscribe to the current block timestamp, updates automatically
+ * api.st.timestamp.now((error, timestamp) => {
+ *   const elapsed = last
+ *     ? `, ${timestamp.toNumber() - last}s since last`
+ *     : '';
+ *
+ *   last = timestamp.toNumber();
+ *   console.log(`timestamp ${timestamp}${elapsed} (${blockPeriod}s target)`);
+ * });
+ * ```
+ * <BR>
+ *
+ * Submitting a transaction -
+ * <BR>
+ *
+ * ```javascript
+ * import ApiPromise from '@polkadot/api/promise';
+ *
+ * ApiPromise.create().then((api) => {
+ *   const nonce = await api.st.system.accountNonce(keyring.alice.address());
+ *
+ *   api.tx.balances
+ *     // create transfer
+ *     transfer(keyring.bob.address(), 12345)
+ *     // sign the transcation
+ *     .sign(keyring.alice, nonce)
+ *     // send the transaction
+ *     .send()
+ *     // retrieve the overall result
+ *     .then((hash) => {
+ *       console.log(`submitted with hash ${hash}`);
+ *     });
+ * });
+ * ```
+ */
 export default class ApiPromise extends ApiBase<Rpc, QueryableStorage, SubmittableExtrinsics> implements ApiPromiseInterface {
   private _isReady: Promise<ApiPromise>;
 
@@ -109,8 +184,16 @@ export default class ApiPromise extends ApiBase<Rpc, QueryableStorage, Submittab
   }
 
   private decorateStorageEntry (method: StorageFunction): QueryableStorageFunction {
-    const decorated: any = (arg: any): Promise<Base | null | undefined> =>
-      this.rpc.state.getStorage([method, arg]);
+    const decorated: any = (...args: Array<any>): Promise<Base | null | undefined> => {
+      if (args.length === 0 || !isFunction(args[args.length - 1])) {
+        return this.rpc.state.getStorage([method, args[0]]);
+      }
+
+      return this.rpc.state.storage(
+        [[method, args.length === 1 ? undefined : args[0]]],
+        args[args.length - 1]
+      );
+    };
 
     return this.decorateFunctionMeta(method, decorated) as QueryableStorageFunction;
   }
diff --git a/packages/api/src/rx/index.ts b/packages/api/src/rx/index.ts
index fddfaa07c8..0962153dc6 100644
--- a/packages/api/src/rx/index.ts
+++ b/packages/api/src/rx/index.ts
@@ -20,6 +20,92 @@ import { StorageFunction } from '@polkadot/types/StorageKey';
 
 const l = logger('api-rx');
 
+/**
+ * @description
+ * ApiRx is a powerfull RxJS Observable wrapper around the RPC and interfaces on the Polkadot network. As a full Observable API, all interface calls return RxJS Observables, including the static `.create(...)`. In the same fashion and subscription-based methods return long-running Observables that update with the latest values.
+ *
+ * The API is well suited to real-time applications where the latest state is needed, unlocking the subscription-based features of Polkadot (and Substrate) clients. Some familiarity with RxJS is a requirement to use the API, however just understanding `.subscribe` and `.pipe` on Observables will unlock full-scale use thereof.
+ *
+ * @example
+ * <BR>
+ *
+ * Making rpc calls -
+ * <BR>
+ *
+ * ```javascript
+ * import ApiRx from '@polkadot/api/rx';
+ *
+ * // initialise via Promise & static create
+ * const api = await ApiRx.create().toPromise();
+ *
+ * // make a call to retrieve the current network head
+ * api.rpc.chain.newHead().subscribe((header) => {
+ *   console.log(`Chain is at #${header.blockNumber}`);
+ * });
+ * ```
+ * <BR>
+ *
+ * Subscribing to chain state -
+ * <BR>
+ *
+ * ```javascript
+ * import { ApiRx } from '@polkadot/api';
+ * import WsProvider from '@polkadot/rpc-provider/ws';
+ * import { combineLatest } from 'rxjs';
+ *
+ * let last = 0;
+ *
+ * // initialise via isReady & new with specific non-local endpoint
+ * new ApiRx(new WsProvider('wss://example.com:9944'))
+ *   .isReady
+ *   .pipe(
+ *     switchMap((api) =>
+ *       combineLatest([
+ *         api.st.timestamp.blockPeriod(),
+ *         api.st.timestamp.now()
+ *       ])
+ *   )
+ *   .subscribe(([blockPeriod, timestamp]) => {
+ *     const elapsed = last
+ *       ? `, ${timestamp.toNumber() - last}s since last`
+ *       : '';
+ *
+ *     last = timestamp.toNumber();
+ *     console.log(`timestamp ${timestamp}${elapsed} (${blockPeriod}s target)`);
+ *   });
+ * ```
+ * <BR>
+ *
+ * Submitting a transaction -
+ * <BR>
+ *
+ * ```javascript
+ * import ApiRx from '@polkadot/api/rx';
+ *
+ * // get api via Promise
+ * const api = await ApiRx.create().toPromise();
+ *
+ * // retrieve nonce for the account
+ * api.st.system
+ *   .accountNonce(keyring.alice.address())
+ *   .pipe(
+ *      // pipe nonce into transfer
+ *      switchMap((nonce) =>
+ *        api.tx.balances
+ *          // create transfer
+ *          .transfer(keyring.bob.address(), 12345)
+ *          // sign the transcation
+ *          .sign(keyring.alice, nonce)
+ *          // send the transaction
+ *          .send()
+ *      )
+ *   )
+ *   // subscribe to overall result
+ *   .subscribe((hash) => {
+ *     console.log(`submitted with hash ${hash}`);
+ *   });
+ * ```
+ */
 export default class ApiRx extends ApiBase<RpcRx, QueryableStorage, SubmittableExtrinsics> implements ApiRxInterface {
   private _isReady: Observable<ApiRx>;
 
@@ -33,7 +119,7 @@ export default class ApiRx extends ApiBase<RpcRx, QueryableStorage, SubmittableE
    * import Api from '@polkadot/api/rx';
    *
    * Api.create().subscribe((api) => {
-   *   api.st.timestamp.now((timestamp) => {
+   *   api.st.timestamp.now.subscribe((timestamp) => {
    *     console.log(`lastest block timestamp ${timestamp}`);
    *   });
    * });
diff --git a/packages/rpc-core/README.md b/packages/rpc-core/README.md
index 14798580b4..02f1c84421 100644
--- a/packages/rpc-core/README.md
+++ b/packages/rpc-core/README.md
@@ -1,13 +1,3 @@
-[![polkadotjs](https://img.shields.io/badge/polkadot-js-orange.svg?style=flat-square)](https://polkadot.js.org)
-![isc](https://img.shields.io/badge/license-ISC-lightgrey.svg?style=flat-square)
-[![style](https://img.shields.io/badge/code%20style-semistandard-lightgrey.svg?style=flat-square)](https://github.com/Flet/semistandard)
-[![npm](https://img.shields.io/npm/v/@polkadot/api.svg?style=flat-square)](https://www.npmjs.com/package/@polkadot/api)
-[![travis](https://img.shields.io/travis/polkadot-js/api.svg?style=flat-square)](https://travis-ci.org/polkadot-js/api)
-[![maintainability](https://img.shields.io/codeclimate/maintainability/polkadot-js/api.svg?style=flat-square)](https://codeclimate.com/github/polkadot-js/api/maintainability)
-[![coverage](https://img.shields.io/coveralls/polkadot-js/api.svg?style=flat-square)](https://coveralls.io/github/polkadot-js/api?branch=master)
-[![dependency](https://david-dm.org/polkadot-js/api.svg?style=flat-square&path=package/rpc-core)](https://david-dm.org/polkadot-js/api?path=package/rpc-core)
-[![devDependency](https://david-dm.org/polkadot-js/api/dev-status.svg?style=flat-square&path=package/rpc-core)](https://david-dm.org/polkadot-js/api?path=package/rpc-core#info=devDependencies)
-
 # @polkadot/rpc-core
 
 This library provides a clean wrapper around all the methods exposed by a Polkadot network client.
diff --git a/packages/rpc-provider/README.md b/packages/rpc-provider/README.md
index e54d768781..a74aa73425 100644
--- a/packages/rpc-provider/README.md
+++ b/packages/rpc-provider/README.md
@@ -1,13 +1,3 @@
-[![polkadotjs](https://img.shields.io/badge/polkadot-js-orange.svg?style=flat-square)](https://polkadot.js.org)
-![isc](https://img.shields.io/badge/license-ISC-lightgrey.svg?style=flat-square)
-[![style](https://img.shields.io/badge/code%20style-semistandard-lightgrey.svg?style=flat-square)](https://github.com/Flet/semistandard)
-[![npm](https://img.shields.io/npm/v/@polkadot/rpc-provider.svg?style=flat-square)](https://www.npmjs.com/package/@polkadot/rpc-provider)
-[![travis](https://img.shields.io/travis/polkadot-js/api.svg?style=flat-square)](https://travis-ci.org/polkadot-js/api)
-[![maintainability](https://img.shields.io/codeclimate/maintainability/polkadot-js/api.svg?style=flat-square)](https://codeclimate.com/github/polkadot-js/api/maintainability)
-[![coverage](https://img.shields.io/coveralls/polkadot-js/api.svg?style=flat-square)](https://coveralls.io/github/polkadot-js/api?branch=master)
-[![dependency](https://david-dm.org/polkadot-js/api.svg?style=flat-square&path=packages/rpc-provider)](https://david-dm.org/polkadot-js/api?path=packages/rpc-provider)
-[![devDependency](https://david-dm.org/polkadot-js/api/dev-status.svg?style=flat-square&path=packages/rpc-provider)](https://david-dm.org/polkadot-js/api?path=packages/rpc-provider#info=devDependencies)
-
 # @polkadot/rpc-provider
 
 Generic transport providers to handle the transport of method calls to and from Polkadot clients from applications interacting with it. Generally, unless you are operating at a low-level and taking care of encoding and decoding of parameters/results, it won't be directly used. API interfaces building on top these providers can support various transports with the same underlying interfaces.
diff --git a/packages/rpc-rx/README.md b/packages/rpc-rx/README.md
index 2a8e85a822..2fa7fa02aa 100644
--- a/packages/rpc-rx/README.md
+++ b/packages/rpc-rx/README.md
@@ -1,13 +1,3 @@
-[![polkadotjs](https://img.shields.io/badge/polkadot-js-orange.svg?style=flat-square)](https://polkadot.js.org)
-![isc](https://img.shields.io/badge/license-ISC-lightgrey.svg?style=flat-square)
-[![style](https://img.shields.io/badge/code%20style-semistandard-lightgrey.svg?style=flat-square)](https://github.com/Flet/semistandard)
-[![npm](https://img.shields.io/npm/v/@polkadot/rpc-rx.svg?style=flat-square)](https://www.npmjs.com/package/@polkadot/rpc-rx)
-[![travis](https://img.shields.io/travis/polkadot-js/api.svg?style=flat-square)](https://travis-ci.org/polkadot-js/api)
-[![maintainability](https://img.shields.io/codeclimate/maintainability/polkadot-js/api.svg?style=flat-square)](https://codeclimate.com/github/polkadot-js/api/maintainability)
-[![coverage](https://img.shields.io/coveralls/polkadot-js/api.svg?style=flat-square)](https://coveralls.io/github/polkadot-js/api?branch=master)
-[![dependency](https://david-dm.org/polkadot-js/api.svg?style=flat-square&path=packages/rpc-rx)](https://david-dm.org/polkadot-js/api?path=packages/rpc-rx)
-[![devDependency](https://david-dm.org/polkadot-js/api/dev-status.svg?style=flat-square&path=packages/rpc-rx)](https://david-dm.org/polkadot-js/api?path=packages/rpc-rx#info=devDependencies)
-
 # @polkadot/rpc-rx
 
 An RxJs wrapper around the [@polkadot/rpc-core](../rpc-core).
diff --git a/packages/type-jsonrpc/README.md b/packages/type-jsonrpc/README.md
index 6102aded2b..acd647a5be 100644
--- a/packages/type-jsonrpc/README.md
+++ b/packages/type-jsonrpc/README.md
@@ -1,13 +1,3 @@
-[![polkadotjs](https://img.shields.io/badge/polkadot-js-orange.svg?style=flat-square)](https://polkadot.js.org)
-![isc](https://img.shields.io/badge/license-ISC-lightgrey.svg?style=flat-square)
-[![style](https://img.shields.io/badge/code%20style-semistandard-lightgrey.svg?style=flat-square)](https://github.com/Flet/semistandard)
-[![npm](https://img.shields.io/npm/v/@polkadot/jsonrpc.svg?style=flat-square)](https://www.npmjs.com/package/@polkadot/jsonrpc)
-[![travis](https://img.shields.io/travis/polkadot-js/api.svg?style=flat-square)](https://travis-ci.org/polkadot-js/api)
-[![maintainability](https://img.shields.io/codeclimate/maintainability/polkadot-js/api.svg?style=flat-square)](https://codeclimate.com/github/polkadot-js/api/maintainability)
-[![coverage](https://img.shields.io/coveralls/polkadot-js/api.svg?style=flat-square)](https://coveralls.io/github/polkadot-js/api?branch=master)
-[![dependency](https://david-dm.org/polkadot-js/api.svg?style=flat-square&path=packages/type-jsonrpc)](https://david-dm.org/polkadot-js/api?path=packages/type-jsonrpc)
-[![devDependency](https://david-dm.org/polkadot-js/api/dev-status.svg?style=flat-square&path=packages/type-jsonrpc)](https://david-dm.org/polkadot-js/api?path=packages/type-jsonrpc#info=devDependencies)
-
 # @polkadot/jsonrpc
 
 A definition of all the methods exposed in a general Polkadot client application. These are used not only to provide a comprehensive code-generated document of the available methods, but are also used in the API to auto-generate endpoints with the required type-checking.
diff --git a/packages/type-storage/README.md b/packages/type-storage/README.md
index f6506f6545..4d606eb7ae 100644
--- a/packages/type-storage/README.md
+++ b/packages/type-storage/README.md
@@ -1,13 +1,3 @@
-[![polkadotjs](https://img.shields.io/badge/polkadot-js-orange.svg?style=flat-square)](https://polkadot.js.org)
-![isc](https://img.shields.io/badge/license-ISC-lightgrey.svg?style=flat-square)
-[![style](https://img.shields.io/badge/code%20style-semistandard-lightgrey.svg?style=flat-square)](https://github.com/Flet/semistandard)
-[![npm](https://img.shields.io/npm/v/@polkadot/storage.svg?style=flat-square)](https://www.npmjs.com/package/@polkadot/storage)
-[![travis](https://img.shields.io/travis/polkadot-js/api.svg?style=flat-square)](https://travis-ci.org/polkadot-js/api)
-[![maintainability](https://img.shields.io/codeclimate/maintainability/polkadot-js/api.svg?style=flat-square)](https://codeclimate.com/github/polkadot-js/api/maintainability)
-[![coverage](https://img.shields.io/coveralls/polkadot-js/api.svg?style=flat-square)](https://coveralls.io/github/polkadot-js/api?branch=master)
-[![dependency](https://david-dm.org/polkadot-js/api.svg?style=flat-square&path=packages/type-storage)](https://david-dm.org/polkadot-js/api?path=packages/type-storage)
-[![devDependency](https://david-dm.org/polkadot-js/api/dev-status.svg?style=flat-square&path=packages/type-storage)](https://david-dm.org/polkadot-js/api?path=packages/type-storage#info=devDependencies)
-
 # @polkadot/storage
 
 An base interface to the storage layer
diff --git a/typedoc.js b/typedoc.js
index 12cc85ad61..df25337b21 100644
--- a/typedoc.js
+++ b/typedoc.js
@@ -3,9 +3,10 @@ module.exports = {
   exclude: [],
   excludeExternals: true,
   excludeNotExported: true,
+  excludeProtected: true,
   excludePrivate: true,
   hideGenerator: true,
-  includeDeclarations: true,
+  includeDeclarations: false,
   out: 'docs',
   module: 'commonjs',
   moduleResolution: 'node',