Improve doc and add images

source/api.md

@@ -1,24 +1,34 @@
 # Public API
-The API is an alternative and easier access to the information on
+The API is an alternative and easier way to access to the information on
 the smart contracts.
 
-It was built to make the information more accessible, so it hides the barriers 
+It was built to make the information more accessible, so it hides the barriers
 that a newcomer may find in the Ethereum development.
 
-The API is accesible for:
+The API is accessible for:
   * **Mainnet**: [https://dutchx.d.exchange/api](https://dutchx.d.exchange/api)
   * **Rinkeby**: [https://dutchx-rinkeby.d.exchange/api](https://dutchx-rinkeby.d.exchange/api)
 
+The API provides a simple way to browse over all methods:
+
+![API docs](_static/api-docs.png)
+
+Also you can use the **TRY** button to test the endpoint:
+
+<p align="center">
+  <img src="_static/api-docs-try-functionality.png" width="500px" alt="Try endpoint" />
+</p>
+
 The API is Open Source, so anyone can run it in it's own server.
 
-It provides read-only access. For any operation that needs to write in the 
-blockchain, you'll need to do it using your own node (or infura). Checkout 
+It provides read-only access. For any operation that needs to write in the
+blockchain, you'll need to do execute it using your own node (or infura). Checkout
 how to do this by reading [Build on top of the Dutch Exchange](./build-on-top-of-dutchx.html)
 
 The API logic is implemented in the [DutchX Services](https://github.com/gnosis/dx-services),
 for more information checkout [DutchX as an open platform](./dutchx-as-an-open-platform.html)
 
-For developers, it should be very easy to get information form the API, check 
-out for example 
-[DutchX Example: How to use the API](https://github.com/gnosis/dx-examples-api) 
-project.
+For developers, it should be very easy to get information form the API, check
+out for example
+[DutchX Example: How to use the API](https://github.com/gnosis/dx-examples-api)
+project.

source/build-on-top-of-dutchx.md

@@ -1,19 +1,24 @@
 # Build on top of the DutchX
-For folowing this, you should be familiar with:
+For following this guide, you should be familiar with:
 * Basics about Ethereum network
 * Truffle projects
 * Node and NPM
 
 **Create your new cool-app**
+
 The easiest way to get started is to create a new node project that depends on
-the [dx-contracts](https://github.com/gnosis/dx-contracts/tree/master/contracts) 
+the [DutchX Smart Contracts](https://github.com/gnosis/dx-contracts/tree/master/contracts)
 project.
 
-**DutchX** publish a [NPM package](https://www.npmjs.com/package/@gnosis.pm/dx-contracts) with:
+The DutchX is available as a
+[NPM package](https://www.npmjs.com/package/@gnosis.pm/dx-contracts) with:
 * All the compiled contracts (ABI, meta info, addresses)
 * Migration code (useful for `development`)
 * Some scripts
 
-So Just follow the steps and create your `cool-app` following the steps 
+So Just follow the steps and create your `cool-app` following the steps
 described in this project:
 [Build on top of the DutchX](https://github.com/gnosis/dx-examples-dev/tree/master/01_build-of-top-of-dx)
+
+Once you have the guide completed, a good idea is continuing with the guide
+[Use DutchX as an Oracle](./use-dutchx-as-an-oracle.html).

source/cli.md

@@ -1,16 +1,22 @@
 # CLI
-The Command Line Interface it’s a very useful tool for invoking some operations 
-in the smart contracts such as posting sell/buy orders, and to extract some 
-information from them (for example getting the status of a token pair).
+The Command Line Interface it’s a very useful tool for invoking some operations
+in the smart contracts such as:
+* Get the DutchX account **balance** for any account.
+* **Deposit** or **withdraw** funds into/from your DutchX account balance.
+* Check the **state** of a given token pair: Auction index, sell/buy volume,
+start time, estimated closing time, etc.
+* Post a sell order or a buy order.
+* Claim back your tokens once the auction has cleared.
+* ..and many other useful operations.
 
-It can be used in test nets like `rinkeby` or in `mainnet`.
+It can be used both, in test-nets like `rinkeby`, or in `mainnet`.
 
-The easiest way to use the CLI is to follow the steps described in 
+The easiest way to use the CLI is to follow the steps described in
 [DutchX Example: How to use the CLI ](https://github.com/gnosis/dx-examples-cli).
 
 The CLI logic is implemented in the [DutchX Services](https://github.com/gnosis/dx-services),
 for more information checkout [DutchX as an open platform](./dutchx-as-an-open-platform.html)
 
-Although the CLI is a very useful took to do some basic interactions with the
-smart contracts, to build tools, bots or services that interact with the 
-DutchX, it's a better approach to [Build on top of the DutchX](./build-on-top-of-dutchx.html)
+Although the CLI is a very useful tool to do some basic interactions with the
+smart contracts, to build tools, bots or services that interact with the
+DutchX, it's a better approach to [Build on top of the DutchX](./build-on-top-of-dutchx.html).

source/contribute.md

@@ -1,13 +1,13 @@
 # Contribute
-DutchX it's **100% open source** and it's been build as a comunity effort to improve
-the problems inherit from centralized platforms or other decentralized ones.
+DutchX it's **100% open source** and it's been build as a community effort to improve
+the problems inherit from centralised platforms or other decentralised ones.
 
 The community is what makes DutchX great.
 
-Became part of it and contribute to create new interfaces, improve the tools, 
+Became part of it and contribute to create new interfaces, improve the tools,
 and spread the word.
 
-Meet the comunity in Github and the [Gitter channel](https://gitter.im/gnosis/DutchX).
+Meet the community in Github and the [Gitter channel](https://gitter.im/gnosis/DutchX).
 
-Checkout the **Developer Guides** and document 
-[DutchX as an open platform](dutchx-as-an-open-platform.html).
+Checkout the **Developer Guides** and document
+[DutchX as an open platform](dutchx-as-an-open-platform.html).

source/dutchx-as-an-open-platform.md

@@ -1,68 +1,82 @@
 # DutchX as an open platform
-DutchX it's **100% open source** and it's been build as a comunity effort to improve
-the problems inherit from centralized platforms or other decentralized ones.
+DutchX it's **100% open source** and it's been build as a community effort to improve
+the problems inherit from centralised platforms or other decentralised ones.
+
+DutchX is an ecosystem of interfaces, on chain apps, and smart contracts that
+create a common liquidity pool that all users can benefit from.
+
+![Open Platform](./_static/open-platform.png)
 
 ## Smart contracts
 The core of the project is the Smart Contracts, that hold the logic described in
-the [Smart Contract Documentation](./smart-contract-documentation.html), and 
+the [Smart Contract Documentation](./smart-contract-documentation.html), and
 can be found in [https://github.com/gnosis/dx-contracts](https://github.com/gnosis/dx-contracts)
 
+The smart contracts is the base of this open platform, and anyone can build
+tools, applications and interfaces on top of them, making the DutchX a unique
+fair protocol to exchange tokens.
+
 The main contract are:
-* [**DutchExchange.sol**](https://github.com/gnosis/dx-contracts/blob/master/contracts/DutchExchange.sol): 
+* [**DutchExchange.sol**](https://github.com/gnosis/dx-contracts/blob/master/contracts/DutchExchange.sol):
 The one holding all the Dutch Auction mechanisms. It will have for example the
 logic for adding a new token pair, posting a sell order or a buy order.
 * [**DutchExchangeProxy.sol**](https://github.com/gnosis/dx-contracts/blob/master/contracts/DutchExchangeProxy.sol):
 The contract that act as an intermediary between the users and the core contract.
 This contract is the one holding the data of the DutchX, so it's the one we should
-use to interact with the DutchX. Please, read more about the Proxy Pattern for 
+use to interact with the DutchX. Please, read more about the Proxy Pattern for
 Smart Contracts in this <a href="https://blog.gnosis.pm/solidity-delegateproxy-contracts-e09957d0f201" target="_blank">Solidity DelegateProxy</a> post.
 
+Security was the main focus on the design and implementation of the DutchX.
+Check out the [Security in DutchX](./security-of-the-contracts.html).
+
 ## Services, API, Bots and CLI
 Another important piece on the DutchX is the [DutchX services](https://github.com/gnosis/dx-services) project.
 
 This project uses the smart contract as a base layer, and build some
  repositories, services and utilities on top of it.
 
-This project may be splited into different smaller ones in the future.
+This project may be split into different smaller ones in the future.
+
 It has the following parts:
 * **Repositories**: Abstraction on top of the smart contracts to make it easier
 to interact with them. For example, they add the same validations that are going
-to be performed in the smart contract, so they can throw more meaninful errors,
+to be performed in the smart contract, so they can throw more meaningful errors,
 instead of the `revert` that smart contracts throw.
-* **Services**: Some use cases built on top of the DutchX
+* **Services**: Some use cases built on top of the DutchX. The CLI, Bots and API
+ use this layer to perform all it's tasks.
 * **API**: REST Api that provides a simpler access to the data in the DutchX.
 Check out the [API documentation](./api.html)
 * **CLI**: The Command Line Interface it's a very useful tool for invoking some
-operations in the smart contracts such as posting sell/buy orders, and to 
-extract some information from them (for example getting the status of a token 
+operations in the smart contracts such as posting sell/buy orders, and to
+extract some information from them (for example getting the status of a token
 pair).
-It can be used in test nets like`rinkeby` or in `mainnet`.
-Learn more about the CLI in the guide [Use the CLI](./cli.html)
-* **Bots**: The bots are series of small applications that run in the background 
-and have a scoped task to fulfill. They interact with the DutchX performing some
-operations. For example the liquidity bots watch some markets and provide 
-liquidity ensuring the auctions run continuosly and the prices don't drop below
+It can be used in test nets like `rinkeby` or in `mainnet`.
+Learn more about the [CLI](./cli.html) page.
+* **Bots**: The bots are series of small applications that run in the background
+and have a scoped task to fulfil. They interact with the DutchX performing some
+operations. For example the liquidity bots watch some markets and provide
+liquidity ensuring the auctions run continuously and the prices don't drop below
 market price. Learn more about the bots in the guide.
 [Run your own bots](./run-your-own-bots.html)
 
 ## Seller interface
 The seller interface is a nice interface that allows users to participate in the
 auctions in a simple way. It can be found in [https://github.com/gnosis/dx-react](https://github.com/gnosis/dx-react).
 
-For using it, you just need to install the [Metamask](https://metamask.io/) 
-plugin. Of course you will also need to hold the tokens you want to trade in 
+For using it, you just need to install the [Metamask](https://metamask.io/)
+plugin. Of course you will also need to hold the tokens you want to trade in
 that account.
 
 Checkout the [**DutchX Web DEMO in Rinkeby**](https://dutchx-rinkeby.d.exchange/).
 
-This interface can be used by anyone as a base to build alternative ones, a 
-buyer interface, or just host it in any server. Soo feel free to contribute to 
+This interface can be used by anyone as a base to build alternative ones, a
+buyer interface, or just host it in any server. So feel free to contribute to
 the DutchX ecosystem.
 
 ## Contribute
-The community is what makes DutchX great. 
+The community is what makes DutchX great.
 
-Became part of it and contribute to create new interfaces, improve the tools, 
+Became part of it and contribute to create new interfaces, improve the tools,
 and spread the word.
 
-Meet the comunity in Github and the [Gitter channel](https://gitter.im/gnosis/DutchX).
+Meet the community in Github and the [Gitter channel](https://gitter.im/gnosis/DutchX).

source/index.rst

@@ -5,7 +5,7 @@
     :class: dutchx-logo
 
 
-The **Dutch Exchange (DutchX)** is a fully decentralized exchange, which
+The **Dutch Exchange (DutchX)** is a fully decentralised exchange, which
 allows **everyone** to add any trading token pair.
 
 It uses the `Dutch auction`_ principle, to prevent the problems that
@@ -24,7 +24,7 @@ Some interesting links to learn all about the mechanisms of the DutchX are:
 
 Documentation for the Smart Contracts
 -------------------------------------
-To get a deeper knowdedge about the DutchX mechanisms, and the math behind them,
+To get a deeper knowledge about the DutchX mechanisms, and the math behind them,
 check out the :download:`DutchX Documentation <./_static/docs/DutchX_Documentation.pdf>` for the smart contracts.
 
 
@@ -54,26 +54,29 @@ check out the :download:`DutchX Documentation <./_static/docs/DutchX_Documentati
 .. toctree::
    :maxdepth: 2
    :caption: Reference:
-  
+
    smart-contracts_addresses
    Github: Smart Contracts <https://github.com/gnosis/dx-contracts>
    Github: Seller Web <https://github.com/gnosis/dx-react>
    Github: API, Bots, CLI, services <https://github.com/gnosis/dx-services>
-
 
-You may be also interested on
+
+Related Github projects
 -----------------------------
-Related github projects:
 
 * **Smart contracts**: https://github.com/gnosis/dx-contracts
 * **Seller interface for DutchX**: https://github.com/gnosis/dx-react
+* **Services, API, Bots and CLI**: https://github.com/gnosis/dx-services
+
+**Examples and guides**:
+* **Examples on how to build on top of the DutchX**: https://github.com/gnosis/dx-examples-dev
 * **Example on using the bots**: https://github.com/gnosis/dx-examples-liquidity-bots
 * **Example on using the read API**: https://github.com/gnosis/dx-examples-api
 * **Example on using the CLI**: https://github.com/gnosis/dx-examples-cli
 
-Contact the DutchX comunity
-===========================
-Find the comunity in: https://gitter.im/gnosis/DutchX
+Contact the DutchX community
+==============================
+Find the community in: https://gitter.im/gnosis/DutchX
 
 .. _Dutch auction: https://en.wikipedia.org/wiki/Dutch_auction
-.. _ERC20: https://github.com/ethereum/EIPs/blob/master/EIPS/eip-20.md
+.. _ERC20: https://github.com/ethereum/EIPs/blob/master/EIPS/eip-20.md

source/market-makers.md

@@ -1,14 +1,14 @@
 # Market Makers
-The DutchX is an open, decentralized trading protocol for ERC20 tokens using
+The DutchX is an open, decentralised trading protocol for ERC20 tokens using
 the Dutch auction mechanism to determine a fair value for the tokens.
 
 Market Makers are a fundamental piece of the DutchX, and they can benefit from
 all the advantages that the DutchX can offer.
 
-For more information, check out: 
+For more information, check out:
 <a href="_static/docs/DutchX_Market_Makers.pdf" download>DutchX for Market Makers</a>
 
 Also, if you are a Market Maker, you might be interested in:
-  * [Add a trading token pair to DutchX](./add-token-pair.html)
+  * [Add a token pair to DutchX](./add-token-pair.html)
   * [DutchX as an open platform](./dutchx-as-an-open-platform.html)
-  * [Run your own bots](./run-your-own-bots.html)
+  * [Run your own bots](./run-your-own-bots.html)

source/run-your-own-bots.md

@@ -1,22 +1,24 @@
 # Run your own bots for DutchX
-The bots are series of small applications that run in the background and have a 
-scoped task to fulfill. 
+The bots are series of small applications that run in the background and have a
+scoped task to fulfil.
 
 They interact with the DutchX performing some operations.
 
 For example the **liquidity bots** watch some markets and provide liquidity ensuring
-the auctions run continuosly and the prices don't drop below market price.
+the auctions run continuously and the prices don't drop below market price.
 
 Running the bots is important for markets were there's insufficient volume or a
 market maker in place.
 
-The bots are implemented in 
-[DutchX Services](https://github.com/gnosis/dx-services) project and are Open 
+![Bots cycle](./_static/bots-cycle.png)
+
+The bots are implemented in
+[DutchX Services](https://github.com/gnosis/dx-services) project and are Open
 Source for anyone to use, modify or improve.
 
 For more information, and details on a easy way on how to run them visit:
 * [https://github.com/gnosis/dx-examples-liquidity-bots](https://github.com/gnosis/dx-examples-liquidity-bots)
 
 You may be also interested in:
 * [DutchX as an open platform](./dutchx-as-an-open-platform.html)
-* [Add a trading token pair to DutchX](./add-token-pair.html)
+* [Add a token pair to DutchX](./add-token-pair.html)