From f00dc7b91d703081c7c3f9c6ad36c75c07d2240f Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Mon, 7 Feb 2022 10:26:43 +0000 Subject: [PATCH] general neatening --- README.md | 2 +- docs/README.md | 31 ++++++++++--------------------- docs/meta/style-guide.md | 11 ++++++++++- 3 files changed, 21 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index fea7c52..5209f3c 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ Non-goals: ## Project setup -An up to date version of the [`nix` package manager](nixos.org) (>=2.3) is required to build this project. For information on how to install, see the [nixos website](https://nixos.org/download.html). Important: See also [this section](https://github.com/input-output-hk/plutus#nix-advice) on binary caches. +An up to date version of the [`nix` package manager](nixos.org) (>=2.3) is required to build this project. For information on how to install, see the [NixOS website](https://nixos.org/download.html). Important: See also [this section](https://github.com/input-output-hk/plutus#nix-advice) on binary caches. Open a dev-shell with `nix develop` and build with `cabal build`. diff --git a/docs/README.md b/docs/README.md index 2140611..6829bb8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,32 +1,21 @@ -| Spec Status | Impl Status | Last Revision | -|-------------|----------------|---------------| -| WIP | WIP | v0.1 22/01/26 | - --------------------- - -**Spec Ownership:** [Jack Hodgkinson](github.com/jhodgdev) - -**Authors**: [Jack Hodgkinson](github.com/jhodgdev) - -**Current Status**: - --------------------- # Agora specification and documentation -This folder contains all of the specification and architecture documentation of Agora. +This folder contains documents explaining the conceptual background and technical implementation of Agora components. ## Technical design -The `tech-design/` subdirectory contains high level descriptions of architecture involved in building Agora's governance system. +The `tech-design/` subdirectory contains high level descriptions of the architecture of Agora's governance solution. -## Implementation +## Plutarch -Agora makes extensive use of Plutarch. So it's prerequisite for understanding the implementation. Plutarch features an [_extensive_ guide](https://github.com/Plutonomicon/plutarch/blob/master/docs/GUIDE.md), which explains many intricacies of Plutarch and its use. +Agora makes extensive use of [Plutarch](https://github.com/plutonomicon/plutarch). One unfamiliar with the library will be unable to suitably understand the technical parts of this documentation. The maintainers provide an extensive [guide](https://github.com/Plutonomicon/plutarch/blob/master/docs/GUIDE.md) that will familiarise the developer with the language and thereby this set of documentation. ## Glossary -The following is a list of terms that are used frequently: +The following is a list of terms that are used frequently throughout the documentation: -- **Governance Token (GT)**: The token that holds value within the protocol and is used for voting, rewards, etc. _Examples: Liqwid's LQ_. -- **Authority Token (GAT)**: A token that delegates authority of a particular script / token. See [tech-design/authority-token.md](./tech-design/authority-tokens.md) -- **Effect**: The result of a proposal, enforced by an effect script. +- **DAO**: decentralised autonomous organisation. +- **Proposal**: a set of changes to a Cardano protocol, suggested by a community member. Will be enacted, if passed by the community. +- **Governance token (GT)**: the token that confers the right to vote on proposals within the protocol. May affect the user's eligibility for rewards. Examples include Liqwid's LQ. +- **Governance authority token (GAT)**: A token that grant's the effects of a proposal the authority to alter the system. More information can be read [here](./tech-design/authority-tokens.md). +- **Effect**: A script for implementing changes suggested by a proposal. An effect can make numerous changes and a proposal may have multiple effects. diff --git a/docs/meta/style-guide.md b/docs/meta/style-guide.md index c9e7265..3a129c5 100644 --- a/docs/meta/style-guide.md +++ b/docs/meta/style-guide.md @@ -9,9 +9,18 @@ The following words should always be render capitalised: - Agora - Liqwid - LiqwidX +- Nix +- NixOS - Plutus - Plutarch +Sensible exceptions naturally exist, including referencing shell commands (`nix-shell`) or code: + +```haskell +plutarchTerm :: Term s a +plutarchTerm = ... +``` + ## Upper-case terms The following terms should always be rendered in all capital letters: @@ -29,4 +38,4 @@ The following words should always be rendered lower-case (unless used at the beg The following practices should be avoided: -- The use of '&' apart from in proper nouns such as AT&T or commonly-understood abbreviations such as 'R&D'. +- The use of '&' apart from in proper nouns such as AT\&T.