cosmos · gamarin2 · Nov 13, 2018 · Nov 6, 2018 · Nov 7, 2018 · Nov 7, 2018
diff --git a/README.md b/README.md
@@ -17,27 +17,26 @@ It is being used to build `Gaia`, the first implementation of the [Cosmos Hub](h
 **WARNING**: The SDK has mostly stabilized, but we are still making some
 breaking changes.
 
-**Note**: Requires [Go 1.10+](https://golang.org/dl/)
+**Note**: Requires [Go 1.11+](https://golang.org/dl/)
 
 ## Gaia Testnet
 
+To install the binaries, read the [install instructions](./docs/gaia/installation.md)
+
 To join the latest testnet, follow 
-[the guide](./docs/getting-started/join-testnet.md).
+[the guide](./docs/gaia/join-testnet.md).
 
 For status updates and genesis files, see the
 [testnets repo](https://github.com/cosmos/testnets).
 
-## Install
-
-See the 
-[install instructions](./docs/getting-started/installation.md).
 
 ## Quick Start
 
-See the [Cosmos Docs](https://cosmos.network/docs/)
+To learn how the SDK works from a high-level perspective, go to the [SDK Intro](./docs/intro/README.md).
+
+If you want to get started quickly and learn how to build on top of the SDK, please follow the [SDK Application Tutorial](https://github.com/cosmos/sdk-application-tutorial). You can also fork the tutorial's repo to get started building your own Cosmos SDK application.
 
-- [Getting started with the SDK](./docs/sdk/core/intro.md)
-- [SDK Examples](/examples)
+For more, please go to the [Cosmos SDK Docs](./docs/README.md)
 
 ## Disambiguation
 

diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
@@ -11,6 +11,15 @@ module.exports = {
     lastUpdated: "Last Updated",
     nav: [{ text: "Back to Cosmos", link: "https://cosmos.network" }],
     sidebar: [
+      {
+        title: "Overview",
+        collapsable: false,
+        children: [
+          "/intro/README",
+          "/intro/sdk-app-architecture",
+          "/intro/ocap"
+        ]
+      },
       {
         title: "Gaia",
         collapsable: false,
@@ -21,23 +30,21 @@ module.exports = {
           "/gaia/validators/overview",
           "/gaia/validators/security",
           "/gaia/validators/validator-faq",
-          "/gaia/validators/validator-setup"
+          "/gaia/validators/validator-setup",
+          "/gaia/ledger"
         ]
       },
       {
         title: "Clients",
         collapsable: false,
         children: [
-	  "/clients/clients",
-	  "/clients/cli",
-	  "/clients/keys",
-	  "/clients/ledger",
-	  "/clients/node",
-	  "/clients/service-providers",
-	  "/lite/", // this renders the readme
-	  "/lite/getting_started",
-	  "/lite/specification"
-	]
+      	  "/clients/README",
+      	  "/lite/", // this renders the readme
+      	  "/lite/getting_started",
+      	  "/lite/specification",
+          "/clients/cli",
+          "/clients/service-providers"
+      	]
       }
     ]
   }

diff --git a/docs/DOCS_README.md b/docs/DOCS_README.md
@@ -1,4 +1,13 @@
-# Docs Build Workflow
+## Updating the docs
+
+If you open a PR on the Cosmos SDK, it is mandatory to update the relevant documentation in `/docs`. 
+
+- If your change relates to the core SDK (`baseapp`, `store`, ...), please update the `docs/gaia` folder, the `docs/examples` folder and possibly the `docs/spec` folder.
+- If your changes relate specifically to the `gaia` application (not including modules), please modify the `docs/gaia` folder. 
+- If your changes relate to a module, please update the module's spec in `docs/spec`. If the module is used by `gaia` and/or `basecoin`, you might also need to modify `docs/gaia` and/or `docs/examples`.
+- If your changes relate to the core of the CLI or Light-client (not specifically to module's CLI/Rest), please modify the `docs/clients` folder.
+
+## Docs Build Workflow
 
 The documentation for the Cosmos SDK is hosted at:
 
@@ -15,55 +24,55 @@ Besides, gaia-lite API docs are also provided by gaia-lite. The default API docs
 https://localhost:1317/swagger-ui/
 ```
 
-## How It Works
+### How It Works
 
 There is a Jenkins job listening for changes in the `/docs` directory, on both
 the  `master` and `develop` branches. Any updates to files in this directory
 on those branches will automatically trigger a website deployment. Under the hood,
 a private website repository has make targets consumed by a standard Jenkins task.
 
-## README
+### README
 
 The [README.md](./README.md) is also the landing page for the documentation
 on the website. During the Jenkins build, the current commit is added to the bottom
 of the README.
 
-## Config.js
+### Config.js
 
 The [config.js](./.vuepress/config.js) generates the sidebar and Table of Contents
 on the website docs. Note the use of relative links and the omission of
 file extensions. Additional features are available to improve the look
 of the sidebar.
 
-## Links
+### Links
 
 **NOTE:** Strongly consider the existing links - both within this directory
 and to the website docs - when moving or deleting files.
 
 Relative links should be used nearly everywhere, having discovered and weighed the following:
 
-### Relative
+#### Relative
 
 Where is the other file, relative to the current one?
 
 - works both on GitHub and for the VuePress build
 - confusing / annoying to have things like: `../../../../myfile.md`
 - requires more updates when files are re-shuffled
 
-### Absolute
+#### Absolute
 
 Where is the other file, given the root of the repo?
 
 - works on GitHub, doesn't work for the VuePress build
 - this is much nicer: `/docs/hereitis/myfile.md`
 - if you move that file around, the links inside it are preserved (but not to it, of course)
 
-### Full
+#### Full
 
 The full GitHub URL to a file or directory. Used occasionally when it makes sense
 to send users to the GitHub.
 
-## Building Locally
+### Building Locally
 
 To build and serve the documentation locally, run:
 
@@ -94,12 +103,12 @@ python -m SimpleHTTPServer 8080
 
 then navigate to localhost:8080 in your browser.
 
-## Consistency
+### Consistency
 
 Because the build processes are identical (as is the information contained herein), this file should be kept in sync as
 much as possible with its [counterpart in the Tendermint Core repo](https://github.com/tendermint/tendermint/blob/develop/docs/DOCS_README.md).
 
-## Update and Build the RPC docs
+### Update and Build the RPC docs
 
 1. Execute the following command at the root directory to install the swagger-ui generate tool.
     ```

diff --git a/docs/README.md b/docs/README.md
@@ -1,24 +1,40 @@
-# Welcome to the Cosmos Docs!
+# Welcome to the SDK Docs!
+
+Welcome to the SDK docs!
+
 
 ![cosmonaut reading the cosmos docs in space](./cosmos-docs.jpg)
 
-Cosmos is a decentralized network of independent parallel blockchains, each powered by classical BFT consensus algorithms like Tendermint.
+## Learn the SDK
+
+### SDK Intro
+
+If you are a newcomer and would like to learn more about the Cosmos SDK, this **[intro](./sdk.md)** is a good starting place.
+
+### SDK tutorial
+
+If you like to learn by doing, you can follow the **[SDK application tutorial](https://github.com/cosmos/sdk-application-tutorial)**. It showcases how to build an SDK-based blockchain from scratch, and teaches you about the basic principles the SDK in the process. 
+
+## Use the SDK
+
+The following sections contain the information you need if you want to build a fully-fonctional SDK-based blockchain:
+
+>*NOTE*: We are currently working on improving the docs. Some info might be missing. 
 
-The first blockchain in the Cosmos Network is the Cosmos Hub, whose native token is the Atom. Cosmos is a permission-less network, meaning that anybody can build a blockchain on it.
+- [Introduction](./intro/README.md): Contains introductory high-level material on the Cosmos SDK.
+- [Gaia](./gaia/README.md): Contains all documentation related to the gaia application (current name for the Cosmos-Hub). 
+- [Clients](./clients/README.md): Documentation about SDK clients like the SDK Command-Line interface and the SDK Light-client.
+- [Specifications](./spec/README.md): Contains SDK and modules specifications.
 
-Cosmos can interoperate with multiple other applications and cryptocurrencies. By creating a new zone, you can plug any blockchain system into the Cosmos hub and pass tokens back and forth between those zones, without the need for an intermediary.
+If you are reading this on the Cosmos Website, please know that you can find more information on [github](https://github.com/cosmos/cosmos-sdk/tree/develop/docs).
 
-## Quick Start
+## Join the public testnet for the Cosmos Hub
 
-- [Getting started with the SDK](./sdk/core/intro.md)
-- [SDK Examples](../examples)
-- [Join the testnet](./getting-started/join-testnet.md#run-a-full-node)
+To install the latest version of the `gaia` application and join the public testnet, **click [here](./gaia/README.md#join-the-cosmos-hub-public-testnet)**
 
 ## Edit the Documentation
 
 See [this file](./DOCS_README.md) for details of the build process and
 considerations when making changes.
 
-## Version
 
-This documentation is built from the following commit:
diff --git a/docs/clients/node.md → docs/_attic/node.md b/docs/clients/node.md → docs/_attic/node.md
diff --git a/docs/clients/README.md b/docs/clients/README.md
@@ -0,0 +1,18 @@
+# Clients
+
+This section explains contains information on clients for SDK based blockchain. 
+
+>*NOTE*: This section is a WIP. 
+
+## Light-client
+
+Light-clients enable users to interact with your application without having to download the entire state history but with a good level of security. 
+
+- [Overview of light clients](./lite/README.md)
+- [Starting a light-client server](./lite/getting_started.md)
+- [Light-client specification](./lite/specification.md)
+
+## Other clients
+
+- [Command-Line interface for SDK-based blockchain](./cli.md)
+- [Service provider doc](./service-providers.md)
diff --git a/docs/clients/cli.md b/docs/clients/cli.md
@@ -1,8 +1,3 @@
 # CLI
 
-See `gaiacli --help` for more details.
-
-Also see the [testnet
-tutorial](https://github.com/cosmos/cosmos-sdk/tree/develop/cmd/gaia/testnets).
-
-TODO: cleanup the UX and document this properly.
+> TODO: Rewrite this section to explain how CLI works for a generic SDK app. 
diff --git a/docs/clients/lite/getting_started.md b/docs/clients/lite/getting_started.md
@@ -13,7 +13,7 @@ To start a REST server, we need to specify the following parameters:
 For example::
 
 ```bash
-gaiacli rest-server --chain-id=test \
+gaiacli advanced rest-server --chain-id=test \
     --laddr=tcp://localhost:1317 \
     --node tcp://localhost:26657 \
     --trust-node=false
@@ -22,7 +22,7 @@ gaiacli rest-server --chain-id=test \
 The server listens on HTTPS by default. You can set the SSL certificate to be used by the server with these additional flags:
 
 ```bash
-gaiacli rest-server --chain-id=test \
+gaiacli advanced rest-server --chain-id=test \
     --laddr=tcp://localhost:1317 \
     --node tcp://localhost:26657 \
     --trust-node=false \

diff --git a/docs/clients/rest.md b/docs/clients/rest.md
diff --git a/docs/clients/service-providers.md b/docs/clients/service-providers.md
@@ -83,7 +83,7 @@ It will display all the available commands. For each command, you can use the `-
 
 ## Setting up the Rest Server
 
-The Rest Server acts as an intermediary between the front-end and the full-node. You don't need to run the Rest Server on the same machine as the full-node. If you intend to run the Rest Server on another machine, you need to go through the [Installation and configuration](#installation-and-configuration) again on this machine.
+The Rest Server acts as an intermediary between the front-end and the full-node. You don't need to run the Rest Server on the same machine as the full-node. 
 
 To start the Rest server: 
 
@@ -109,4 +109,6 @@ The Rest API documents all the available endpoints that you can use to interract
 
 The API is divided into ICS standards for each category of endpoints. For example, the [ICS20](https://cosmos.network/rpc/#/ICS20/) describes the API to interact with tokens. 
 
-To give more flexibility to implementers, we have separated the different steps that are involved in the process of sending transactions. You will be able to generate unsigned transactions (example with [coin transfer](https://cosmos.network/rpc/#/ICS20/post_bank_accounts__address__transfers)), [sign](https://cosmos.network/rpc/#/ICS20/post_tx_sign) and [broadcast](https://cosmos.network/rpc/#/ICS20/post_tx_broadcast) them with different API endpoints. This allows service providers to use their own signing mechanism for instance. 
+To give more flexibility to implementers, we have included the ability to generate unsigned transactions, [sign](https://cosmos.network/rpc/#/ICS20/post_tx_sign) and [broadcast](https://cosmos.network/rpc/#/ICS20/post_tx_broadcast) them with different API endpoints. This allows service providers to use their own signing mechanism for instance. 
+
+In order to generate an unsigned transaction (example with [coin transfer](https://cosmos.network/rpc/#/ICS20/post_bank_accounts__address__transfers)), you need to use the flag `?generate_only`.
diff --git a/docs/gaia/README.md b/docs/gaia/README.md
@@ -0,0 +1,19 @@
+# Gaia Documentation
+
+Welcome to the `Gaia` docs. `Gaia` is the current name of the Cosmos SDK application for the Cosmos Hub.
+
+## Join the Cosmos Hub public testnet
+
+- [Install the `gaia` application](./installation.md)
+- [Join the current testnet](./join-testnet.md)
+- [Upgrade to a validator node](./validators/validator-setup.md)
+
+## Setup your own `gaia` testnet
+
+- [Setup your own `gaia` testnet](./networks.md)
+
+## Additional resources
+
+- [Intro to validators](./validators/overview.md)
+- [Validator FAQ](./validators/validator-faq.md)
+- [Validator security considerations](./validators/security.md)