Merge pull request #577 from JoinColony/docs/spring-improvements

Docs/spring improvements

Author: kronosapiens

docs/_Docs_GetStarted.md

@@ -1,14 +1,20 @@
 ---
 title: Get Started
 section: Docs
-order: 2
+order: 4
 ---
 
-The [colonyNetwork](https://github.com/JoinColony/colonyNetwork) smart contracts are currently live on `rinkeby` and will soon be live on `mainnet` but the best way to get started is to run your own version on a local network for testing and development.
+The [glider](https://github.com/JoinColony/colonyNetwork) release is currently live on `rinkeby` and will soon be deployed on `mainnet`.
 
-## Prerequisites
+This page is written for developers contributing features or direct smart contract extensions with the Colony Network.
+
+See our [guidelines](https://github.com/JoinColony/colonyNetwork/blob/develop/docs/CONTRIBUTING.md) if you're interested in contributing to the colonyNetwork codebase.
+
+If you want to build a dapp or other integration that doesn't directly extend the Colony Network contracts, it's recommended that you use colonyJS. Analogous instructions for colonyJS can be found in [Local Setup](/colonyjs/intro-local-setup/) for colonyJS.
 
-First of all, we will need to make sure we have all the necessary prerequisites.
+An even more 'complete' starting point is the [colonyStarter kit](/colonystarter/docs-overview/), which contains boilerplate examples for dapp development, including frontend frameworks like react. 
+
+## Prerequisites
 
 ### Node
 

docs/_Docs_NetworkOverview.md

@@ -0,0 +1,75 @@
+---
+title: Overview
+section: Docs
+order: 1
+---
+
+*The colonyNetwork repository is developed as free software; if you are interested in contributing, or want to report an issue or bug, please see the [GitHub repository.](https://github.com/JoinColony/colonyNetwork)*
+
+The Colony Network is a large set of contracts that together define how all colonies operate and interact with people and other smart contracts on the Ethereum blockchain.
+
+Colony is designed to be modular, upgradable, and eternally backwards-compatible. This is achieved through a sophisticated contract architecture that requires a bit of exposition. It is recommended that any developer seeking to understand the Colony Network solidity implementation first read the [Colony Whitepaper](https://colony.io/whitepaper/), or at the very least, the [whitepaper Whitepaper TL;DR](/colonynetwork/whitepaper-tldr-colony/).
+
+==TOC==
+
+## Overview of Contracts
+Broadly speaking, the Colony Network contracts can be divided into a few categories:
+
+* Core contracts that facilitate upgrades, versioning, and emergency functions
+  * `EtherRouter.sol`
+  * `Resolver.sol`
+  * `ContractRecovery.sol`
+  * `ContractEditing.sol`
+
+* Interface contracts that collate and register public functions on the network.
+   * `IColony.sol`
+   * `IMetaColony.sol`
+   * `IColonyNetwork.sol`
+   * `IReputationMiningCycle.sol`
+   * `ITokenLocking.sol`
+   * `IRecovery.sol`
+
+* Authority contracts that define who can call which registered functions.
+   * `CommonAuthority.sol`
+   * `ColonyAuthority.sol`
+   * `ColonyNetworkAuthority.sol`
+
+* Colony contracts that define the state of an individual colony, such as funding pots, tasks, domains, and skills.
+   * `Colony.sol`
+   * `ColonyFunding.sol`
+   * `ColonyTask.sol`
+   * `ColonyStorage.sol`
+   * `ColonyDataTypes.sol`
+
+* Network contracts that define a global state shared by all colonies, such as reputation, token auctions and ENS.
+    * `ColonyNetwork.sol`
+    * `ColonyNetworkAuction.sol`
+    * `ColonyNetworkENS.sol`
+    * `ColonyNetworkMining.sol`
+    * `ColonyNetworkStorage.sol`
+    * `ColonyNetworkDataTypes.sol`
+
+* Reputation Mining contracts that define a consensus protocol for validators of the global reputation state.
+    * `ReputationMiningCycle.sol`
+    * `ReputationMiningCycleDataTypes.sol`
+    * `ReputationMiningCycleStorage.sol`
+    * `ReputationMiningCycleRespond.sol`
+
+* Token contracts that define the CLNY token.
+    * `TokenLocking.sol`
+    * `TokenLockingStorage.sol`
+    * `TokenLockingDataTypes.sol`
+
+
+## Inheritance Architecture
+The Colony Network contracts are separated out into functional layers, and named according to their context.
+
+![Interface, Logic, Data](img/architecture_colonyNetwork_r7.png)
+
+Starting from the lowest level, all data types are declared in a DataTypes contract.
+
+All storage variables are declared and stored in a storage contract, which inherits a DataTypes contract.
+
+The actual logic of functions is implemented in separate contracts, which inherit a storage contract. All functions which are implemented in this layer must only modify storage varibles declared in the appropriate storage contract.
+
+Finally, all public functions are composed from all logic contracts into a single interface contract, which is used to register functions with EtherRouter (see the next section).

docs/_Docs_Overview.md

@@ -0,0 +1,17 @@
+---
+title: Releases
+section: Docs
+order: 3
+---
+
+
+The current colonyNetwork release is `glider`, which implements some, but not all, of the Colony Protocol:
+
+* Tokens and Funding pots
+* Reputation
+* Funding Pots and payments
+* Single-level domains
+* Skill tags
+* Tasks and work ratings
+* Roles and domain-level permissions
+* ENS

docs/_Docs_Releases.md

@@ -1,27 +1,36 @@
 ---
-title: Upgrades to the Colony Network
+title: The Delegate Proxy Pattern
 section: Docs
-order: 10
+order: 2
 ---
+The contracts comprising the Colony Network are upgradeable using the Delegate Proxy design pattern.
 
-Improvements to the Colony Network are expected to be continuously developed and periodically deployed.
+Providing an upgrade path is important to allow for the continuous improvement of the Colony Network. At the same time, all depreciated versions of Colony should remain functional indefinitely after deployment, so that the organizations created are not predicated upon the actions/efforts of a third party.
 
-Providing an upgrade path is important to allow people to use Colony without preventing themselves using new features as they are added to the Network. At the same time, all depreciated versions of Colony should remain functional indefinitely after deployment, so that the organizations created are not predicated upon the actions/efforts of a third party.
+In other words, upgrades to any individual colony on the network are "opt-in", while the network as a whole remains eternally backwards-compatible.
 
-The contracts comprising the Colony Network are upgradeable using the design pattern called EtherRouter.
+## For whom the delegate calls
+Interacting with both the Colony Network and individual colonies on the network is somewhat different than many other smart contract interactions that a blockchain developer might not be accustomed to.
 
-## EtherRouter
-This pattern uses two contracts in addition to the contract(s) providing their intended functionality:
+Rather than calling functions directly from the contract in which they are deployed, all transactions are signed and sent to the `EtherRouter` contract.
 
-* The `EtherRouter` contract which passes transactions (via `delegatecall`) to the contract that implements the called function.
-* A `Resolver` contract where the addresses of the contracts that implement the desired function are defined.
+Whenever a transaction is received by the `EtherRouter` contract, it looks the function up in a `Resolver` contract, using the function signature.
 
-Whenever a transaction is received by the `EtherRouter` contract, it looks up the contract that implements that function (if any) in the `Resolver`, and then `delegatecall`s that contract.
+The `Resolver` contract contains a mapping of whitelisted function signatures to addresses (`mapping ( bytes4 => address )`).
+
+A function signature lookup will return the address of the contracts that implement the desired function. `EtherRouter` in turn calls the function via `delegatecall`, and passes any returns from the call back to `msg.sender`.
 
 ![EtherRouter](img/delegateProxyCallchain_1.png)
 
-In order to upgrade, new contracts are deployed with new functionality, and then contracts that the `Resolver` contract points to must be changed to point to these new contracts.
+This pattern enables both fine-grained control of permissions for individual functions (see below), well as eternal backwards-compatibility following network upgrades. To learn more about planned upgrades to the Colony Network, please see [Releases](/colonynetwork/docs-releases/).
+
+## It calls for `roleId`
+Most functions in colony are *authorized* by a separate contract which defines the rules for who can call which functions. Any function that is decorated with the `auth` modifier will perform an authorization check before granting access to the function.
+
+In the current Glider release, authority is based on roles, which are defined in the relevant "authority" contracts, e.g. `ColonyAuthority.sol`.
+
+Roles within Colony act as a white-list for functions, registering specific addresses to a `Founder` or `Admin` role, approved to call a certain set of functions within a colony.
 
-In order to avoid a situation where the contract partially implements both old and new functionality, a new instance of `Resolver` will be deployed for each upgrade, and then a single transaction can point `EtherRouter` at the new Resolver.
+Roles also are used in task-level permissions. A more specific example of task roles can be seen in the [task workflow](https://docs.colony.io/colonyjs/topics-task-lifecycle/#task-roles).
 
-This pattern applies for both upgrades to individual colonies as well as to the Network-level contracts.
+In future releases, this pattern will allow for reputation-mediated authority in Colony.

docs/_Docs_Upgrades.md

@@ -0,0 +1,56 @@
+---
+title: Welcome
+section: Intro
+order: 0
+---
+
+Colony is a platform for organizations that operate via software rather than paperwork and management hierarchy.
+
+At its core, a colony is a set of smart contracts that describe all aspects of a traditional organization, as well as some new capabilities that would only be possible using a decentralized protocol like Ethereum.
+
+It's infrastructure for the future of the firm, built to organize/incentivize teams, projects, and communities.
+
+### The Colony Protocol
+
+The Colony whitepaper describes a complete protocol for organizations, with crypto-economic processes for:
+
+* Ownership and permissions
+* Reputation
+* Dispute resolution and decision-making
+* Work management and delegation
+* Financial management, including rewards and payments
+
+To learn more about the Colony Protocol, dig in to the [Colony Whitepaper](https://colony.io/whitepaper/) or read the [whitepaper TL;DR](/colonynetwork/whitepaper-tldr-colony/)
+
+### The Colony Network
+The Colony Network is the infrastructure upon which all colonies run.
+
+The colonyNetwork repository contains the solidity implementation of Colony, which is developed as free software. See our [guidelines](https://github.com/JoinColony/colonyNetwork/blob/develop/docs/CONTRIBUTING.md) if you're interested in contributing to the colonyNetwork codebase. Developers interested in contributing to the Colony Network are encouraged to look at the code on [GitHub](https://github.com/JoinColony/colonyNetwork), and to come say hi on [Gitter](https://gitter.im/JoinColony/colonyNetwork).
+
+The current colonyNetwork release is [glider]. Glider implements some, but not all, of the Colony Protocol:
+
+* Ownership and permissions (through roles)
+* Reputation
+* Funding Pots and payments
+* Domains and Skills
+* Tasks and work ratings
+
+To learn more about Glider, see the [releases] page.
+
+The Colony Network is maintained and improved by the [Meta Colony] (which is, itself, a colony on the network with special permissions).
+
+Membership in the Meta Colony is open to all (and heartily encouraged!), but changes such as [network upgrades](/colonynetwork/docs-the-delegate-proxy-pattern/) require a minimum *reputation* within the Meta Colony to proceed.
+
+### ColonyJS (and colonyStarter?)
+ColonyJS is a javascript library designed to make interaction with the Colony Network as straightforward as possible for (d)app developers.
+
+Using colonyJS, all of the functions of a colony can be imported and called as methods within a javascript application.
+
+Things like parsing returned parameters from a transaction, connecting to the right network version, and signing transactions with a wallet provider are all handled by this library.
+
+To learn more about how to use colonyJS with your (d)app, or to get specific info about the colonyJS API, see [the colonyJS docs]
+
+### Developer Forums (to switch to developer portal)
+If you didn't get here from there, have a look at our developer portal for links to [tutorials], [starter kits], and [developer forums].
+
+Or, if you're feeling old skool and just want to chat, send an email to [email protected] to chat with our DevRel team. We're nice people!