Docs: Reference -> Concepts (#3090)

docs/.vuepress/config.js

@@ -49,10 +49,12 @@ module.exports = {
           "/tutorial/queriers",
           "/tutorial/codec",
           "/tutorial/cli",
+          "/tutorial/rest",
           "/tutorial/app-complete",
           "/tutorial/entrypoint",
           "/tutorial/dep",
-          "/tutorial/build-run"
+          "/tutorial/build-run",
+          "/tutorial/run-rest"
         ]
       },
       {

docs/README.md

@@ -25,6 +25,8 @@ The following sections contain the information you need if you want to build a f
 - [Gaia](./gaia/README.md): Contains all documentation related to the gaia application (current name for the Cosmos-Hub). Also contains info on how to join gaia testnets.
 - [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.
+- [SDK API Reference](https://godoc.org/github.com/cosmos/cosmos-sdk): Godocs of the Cosmos-SDK.
+- [REST API spec](https://cosmos.network/rpc/): List of endpoints to interract with a `gaia` full-node through REST.
 
 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). Also if you find any issues with the documentation please [*open a Pull Request*](https://github.com/cosmos/cosmos-sdk/compare?expand=1), or at least [*open an Issue*](https://github.com/cosmos/cosmos-sdk/issues/new) to update the docs!
 

docs/architecture/adr-002-docs-structure.md

@@ -23,7 +23,7 @@ docs/
 │   ├── validator-node.md
 │   ├── validator-faq.md
 │   └── delegator-faq.md    
-├── reference/
+├── concepts/
 │   ├── baseapp
 │   ├── types
 │   ├── store
@@ -49,7 +49,7 @@ The files in each sub-folders do not matter and will likely change. What matters
 - `README`: Landing page of the docs. 
 - `into`: Introductory material. Goal is to have a short explainer of the SDK and then channel people to the resource they need. The [sdk-tutorial](https://github.com/cosmos/sdk-application-tutorial/) will be highlighted, as well as the `godocs`.
 - `gaia`: Contains all docs related to the `gaia` application. Will later be renamed to `cosmos-hub` or `chub` and probably moved to its own repository.
-- `reference`: Contains high-level explanations of the abstractions of the SDK. It does not contain specific code implementation and does not need to be updated often. **It is not an API specification of the interfaces**. API spec is the `godoc`. 
+- `concepts`: Contains high-level explanations of the abstractions of the SDK. It does not contain specific code implementation and does not need to be updated often. **It is not an API specification of the interfaces**. API spec is the `godoc`. 
 - `examples`: Contain a couple examples of sdk application like `basecoin` and `democoin`. Developers need to maintain them up-to-date and make sure they compile as the SDK gets upgraded.
 - `clients`: Contains specs and info about the various SDK clients.
 - `spec`: Contains specs of modules, and others.
@@ -60,14 +60,14 @@ Website docs sidebar will only include the following sections:
 - `README`
 - `intro`
 - `gaia`
-- `reference`
+- `concepts`
 - `clients`
 
 `architecture` and `examples` need not be displayed on the website. As for `modules`, we might need to think about creating a modules manager, but this is out of scope for this document.
 
 ## Status
 
-Proposed
+Accepted
 
 ## Consequences
 
@@ -83,7 +83,7 @@ Proposed
 ### Neutral
 
 - We need to move a bunch of deprecated stuff to `/_attic` folder. 
-- We need to integrate content in `docs/sdk/docs/core` in `reference`.
+- We need to integrate content in `docs/sdk/docs/core` in `concepts`.
 - We need to move all the content that currently lives in `docs` and does not fit in new structure (like `lotion`, intro material, whitepaper) to the website repository.
 - Update `DOCS_README.md`
 

docs/gaia/validators/validator-faq.md

@@ -228,7 +228,7 @@ We have to solve this simple equation to find the reward R for each validator:
 
 If a validator misbehaves, its bonded stake along with its delegators' stake and will be slashed. The severity of the punishment depends on the type of fault. There are 3 main faults that can result in slashing of funds for a validator and its delegators:
 
-* **Double signing:** If someone reports on chain A that a validator signed two blocks at the same height on chain A and chain B, this validator will get slashed on chain A
+* **Double signing:** If someone reports on chain A that a validator signed two blocks at the same height on chain A and chain B, and if chain A and chain B share a common ancestor, then this validator will get slashed on chain A
 * **Unavailability:** If a validator's signature has not been included in the last X blocks, the validator will get slashed by a marginal amount proportional to X. If X is above a certain limit Y, then the validator will get unbonded
 * **Non-voting:** If a validator did not vote on a proposal, its stake will receive a minor slash.