Docs: Restructure governance section (#1126)

* rm gov gaiad page use getting started * restructure proposal type readmes and formatting * rename files to use - vs _ * update links and order pages * move all best practices into a single doc * Apply suggestions from code review Co-authored-by: billy rennekamp <[email protected]> Co-authored-by: billy rennekamp <[email protected]>
cosmos · Jan 19, 2022 · 2bb64bc · 2bb64bc
1 parent f30ca0a
commit 2bb64bc
Show file tree

Hide file tree

Showing 15 changed files with 328 additions and 281 deletions.
diff --git a/docs/governance/README.md b/docs/governance/README.md
@@ -1,30 +1,31 @@
-<!--
-order: false
+---
+order: 1
 parent:
+  title: Governance
   order: 7
--->
+---
 
-# Governance
+# Governance Overview
 
 The Cosmos Hub ("Gaia") has an on-chain governance mechanism for passing
-[text proposals](./text),
+text proposals,
 changing [consensus parameters](./params-change),
 and spending [funds from the community pool](./community-pool-spend).
 
 This repository provides background information on these different kinds of proposals
 and best-practices for drafting them and proposing them on-chain.
 It also provides a place for collaborating on draft proposals in plain text on Github.
 
-If you'd like to draft a proposal, start [here](./best_practices.md).
+If you'd like to draft a proposal, start [here](./best-practices.md).
 See the contents below for more background on the governance system,
 the different types of proposals, and how to submit one.
 
 ## Contents
 
-- [Cosmos On-Chain Governance Overview](./overview.md)
-- [Best Practices for Drafting a Proposal](./best_practices.md)
+- [On-Chain Process](./process.md)
+- [Best Practices for Drafting a Proposal](./best-practices.md)
 - Proposal Types:
-    - [Text Proposal](./text)
+    - Text Proposal
     - [Parameter Change Proposal](./params-change)
     - [Community Spend Proposal](./community-pool-spend)
 - [Submitting a Proposal](./submitting.md)

diff --git a/docs/governance/best_practices.md → docs/governance/best-practices.md b/docs/governance/best_practices.md → docs/governance/best-practices.md
@@ -1,54 +1,131 @@
+---
+order: 3
+---
+
 # Best Practices for Drafting a Proposal 
 
 There are currently three types of proposals supported by the Cosmos Hub: 
-- [Community Pool Spend](./community-pool-spend) - Proposal to spend funds from the community pool on
+- [**Community Pool Spend**](./community-pool-spend) - Proposal to spend funds from the community pool on
   an important project.
-- [Parameter Change](./params-change) - Proposal to change a core on-chain parameter.
-- [Text](./text) - Proposal to agree to a certain strategy, plan, commitment, future
-  upgrade or other statement. Text proposals are exclusively a signalling mechanism and focal point for future coordination - 
+- [**Parameter Change**](./params-change) - Proposal to change a core on-chain parameter.
+- **Text** - Proposal to agree to a certain strategy, plan, commitment, 
+  future upgrade or other statement. Text proposals are exclusively a 
+  signalling mechanism and focal point for future coordination - 
   they do not directly cause any changes.
 
 You'll first want to determine which kind of proposal you are making. Be sure to
-review all details of your specific proposal type. What follows below are
-general best practices, regardless of proposal type.
+review all details of your specific proposal type. 
 
 ## Engage directly with the voting community and seek feedback
 
-Engagement is likely to be critical to the success of a proposal. 
-
-The degree to which you engage with the Cosmos Hub community should be relative to the potential impact that your proposal may have on the stakeholders. 
+Engagement is likely to be critical to the success of a proposal. The degree to which you engage with the Cosmos Hub community should be relative to the potential impact that your proposal may have on the stakeholders. This guide does not cover all ways of engaging: you could bring your idea to a podcast or a hackathon, host an AMA on [Reddit](https://www.reddit.com/r/cosmosnetwork) or host a Q&A (questions & answers). We encourage you to experiment and use your strengths to introduce proposal ideas and gather feedback.
 
 There are many different ways to engage. One strategy involves a few stages of engagement before and after submitting a proposal on chain. **Why do it in stages?** It's a more conservative approach to save resources. The idea is to check in with key stakeholders at each stage before investing more resources into developing your proposal.
 
-In the first stage of this strategy, you should engage people (ideally experts) informally about your idea.
+In the first stage of this strategy, you should engage people (ideally experts) informally about your idea. You'll want to start with the minimal, critical components (name, value to cosmos hub, timeline, any funding needs) and check:
 - Does it make sense? 
 - Are there critical flaws? 
 - Does it need to be reconsidered? 
 
-If you're already confident about your idea, [skip to Stage 2](#stage-2-your-draft-proposal).
+You should be able enagaging with key stakeholders (eg. a large validator operator) with a few short sentences to measure their support. Here's an example:
+
+"We are considering a proposal for funding to work on `project`. We think it will help the Hub to `outcome`. Timeline is `x`, and we're asking for `y` amount. Do you think that this is a proposal that `large validator` may support?"
+
+**Why a large validator?** They tend to be the de facto decision-makers on the Cosmos Hub, since their delegators also delegate their voting power. If you can establish a base layer of off-chain support, you can be more confident that it's worth proceeding to the next stage.
 
-**Note**: this guide likely fails to capture all ways of engaging. Perhaps you could bring your idea to a podcast or a hackathon. You could host an AMA on [Reddit](https://www.reddit.com/r/cosmosnetwork) or host a Q&A (questions & answers) video call. Try to go above and beyond what's recommended here--experiment, and use your strengths and connections.
+**Note:** many will likely hesitate to commit support, and that's okay. It will be important to reassure these stakeholders that this isn't a binding a commitment. You're just canvasing the community to get a feel for whether it's worthwhile to proceed. It's also an opportunity to connect with new people and to answer their questions about what it is you're working on. It will be important for them to clearly understand why you think what you're proposing will be valuable to the Cosmos Hub, and if possible, why it will be valuable to them as long-term stakeholders.
+
+If you're already confident about your idea, [skip to Stage 2](#stage-2-your-draft-proposal).
 
 ## Stage 1: Your Idea
 
 ### Not yet confident about your idea?
+
 Great! Governance proposals potentially impact many stakeholders. Introduce your idea with known members of the community before investing resources into drafting a proposal. Don't let negative feedback dissuade you from exploring your idea if you think that it's still important. 
 
 If you know people who are very involved with the Cosmos Hub, send them a private message with a concise overview of what you think will result from your idea or proposed changes. Wait for them to ask questions before providing details. Do the same in semi-private channels where people tend to be respectful (and hopefully supportive). I recommend the private Cosmos Network VIP Telegram channel (ask for an invite [on the forum][forum] if you are or would like to be a Cosmos contributor).
 
 ### Confident with your idea?
+
 Great! However, remember that governance proposals potentially impact many stakeholders, which can happen in unexpected ways. Introduce your idea with members of the community before investing resources into drafting a proposal. At this point you should seek out and carefully consider critical feedback in order to protect yourself from [confirmation bias](https://en.wikipedia.org/wiki/Confirmation_bias). This is the ideal time to see a critical flaw, because submitting a flawed proposal will waste resources.
 
 ### Are you ready to draft a governance proposal?
+
 There will likely be differences of opinion about the value of what you're proposing to do and the strategy by which you're planning to do it. If you've considered feedback from broad perspectives and think that what you're doing is valuable and that your strategy should work, and you believe that others feel this way as well, it's likely worth drafting a proposal. However, remember that the largest ATOM stakers have the biggest vote, so a vocal minority isn't necessarily representative or predictive of the outcome of an on-chain vote. 
 
 A conservative approach is to have some confidence that you roughly have initial support from a majority of the voting power before proceeding to drafting your proposal. However, there are likely other approaches, and if your idea is important enough, you may want to pursue it regardless of whether or not you are confident that the voting power will support it.
 
 ## Stage 2: Your Draft Proposal
 
-### Begin with a well-considered draft proposal
 The next major section outlines and describes some potential elements of drafting a proposal. Ensure that you have considered your proposal and anticipated questions that the community will likely ask. Once your proposal is on-chain, you will not be able to change it.
 
+### Proposal Elements 
+
+It will be important to balance two things: being detailed and being concise. You'll want to be concise so that people can assess your proposal quickly. You'll want to be detailed so that voters will have a clear, meaningful understanding of what the changes are and how they are likely to be impacted.
+
+There is a [proposal template](./proposals/proposal-template.md) with suggested sections. Each proposal should contain a summmary with key details:
+
+- who is submitting the proposal
+- the amount of the proposal or parameter(s) being changed;
+- and deliverables and timeline
+- a reason for the proposal and potential impacts
+- a short summary of the history (what compelled this proposal), solution that's being presented, and future expectations
+
+Assume that many people will stop reading at this point. However it is important to provide in-depth information, a few more pointers for Parameter-change and Community Spend proposals are below.
+
+#### Parameter-Change
+
+1. Problem/Value - generally the problem or value that's motivating the parameter change(s)
+1. Solution - generally how changing the parameter(s) will address the problem or improve the network
+   - the beneficiaries of the change(s) (ie. who will these changes impact and how?)
+      - voters should understand the importance of the change(s) in a simple way
+1. Risks & Benefits - clearly describe how making this/these change(s) may expose stakeholders to new benefits and/or risks
+1. Supplementary materials - optional materials eg. models, graphs, tables, research, signed petition, etc
+
+
+#### Community-Spend Proposal
+
+1. Applicant(s) - the profile of the person(s)/entity making the proposal
+   - who you are and your involvement in Cosmos and/or other blockchain networks
+   - an overview of team members involved and their relevant experience
+   - brief mission statment for your organization/business (if applicable) eg. website
+   - past work you've done eg. include your Github
+   - some sort of proof of who you are eg. Keybase
+1. Problem - generally what you're solving and/or opportunity you're addressing
+   - past, present (and possibly a prediction of the future without this work being done)
+1. Solution - generally how you're proposing to deliver the solution
+   - your plan to fix the problem or deliver value
+   - the beneficiaries of this plan (ie. who will your plan impact and how?)
+     - follow the "as a user" template ie. write a short user story about the problem you are trying to solve and how users will interact with what you're proposing to deliver (eg. benefits and functionality from a user’s perspective)
+     - voters should understand the value of what you're providing in a simple way
+   - your reasons for selecting this plan
+   - your motivation for delivering this solution/value
+1. Funding - amount and denomination proposed eg. 5000 ATOM
+   - the entity controlling the account receiving the funding
+   - consider an itemized breakdown of funding per major deliverable
+   - consider outlining how the funds will be spent
+1. Deliverables and timeline - the specifics of what you're delivering and how, and what to expect
+   - what are the specific deliverables? (be detailed)
+   - when will each of these be delivered?
+   - will there be a date at which the project will be considered failed if the deliverables have not been met?
+   - how will each of these be delivered?
+   - what will happen if you do not deliver on time?
+     - what is the deadline for the project to be considered failed?
+     - do you have a plan to return the funds?
+   - how will you be accountable to the Cosmos Hub stakeholders?
+     - how will you communicate updates and how often?
+     - how can the community observe your progress?
+     - how can the community provide feedback?
+   - how should the quality of deliverables be assessed? eg. metrics
+1. Relationships and disclosures
+   - have you received or applied for grants or funding? for similar work? eg. from the Interchain Foundation
+   - how will you and/or your organization benefit?
+   - do you see this work continuing in the future and is there a plan?
+   - what are the risks involved with this work?
+   - do you have conflicts of interest to declare?
+
+### Begin with a well-considered draft proposal
+
 The ideal format for a proposal is as a Markdown file (ie. `.md`) in a github repo. Markdown
 is a simple and accessible format for writing plain text files that is easy to
 learn. See the [Github Markdown
@@ -66,6 +143,7 @@ Word or Google Docs, or directly in the forums, or otherwise. However Markdown
 on Github is the ultimate standard for distributed collaboration on text files.
 
 ### Engage the community with your draft proposal
+
 1. Post a draft of your proposal as a topic in the 'governance' category of the [Cosmos forum][forum]. Ideally this should contain a link to this repository, either directly to your proposal if it has been merged, or else to a pull-request containing your proposal if it has not been merged yet.
 2. Directly engage key members of the community for feedback. These could be large contributors, those likely to be most impacted by the proposal, and entities with high stake-backing (eg. high-ranked validators; large stakers).
 3. Engage with the Cosmos Governance Working Group (GWG). These are people focused on Cosmos governance--they won't write your proposal, but will provide feedback and recommend resources to support your work. Members can be contacted on the [forum][forum] (they use the tag 'GWG' in posts) and in [Telegram](https://t.me/hubgov).
@@ -91,13 +169,15 @@ A majority of the voting community should probably be aware of the proposal and
 See the [submitting guide](./submitting.md) for more on submitting proposals.
 
 ### The Deposit Period
+
 The deposit period currently lasts 14 days. If you submitted your transaction with the minimum deposit (512 ATOM), your proposal will immediately enter the voting period. If you didn't submit the minimum deposit amount (currently 512 ATOM), then this may be an opportunity for others to show their support by contributing (and risking) their ATOMs as a bond for your proposal. You can request contributions openly and also contact stakeholders directly (particularly stakeholders who are enthusiastic about your proposal). Remember that each contributor is risking their funds, and you can [read more about the conditions for burning deposits here](./overview.md#burned-deposits).
 
 This is a stage where proposals may begin to get broader attention. Most popular explorers currently display proposals that are in the deposit period, but due to proposal spamming, this may change. [Hubble](https://hubble.figment.network/cosmos/chains/cosmoshub-3/governance), for example, only displays proposals that have 10% or more of the minimum deposit, so 51.2 ATOM or more.
 
 A large cross-section of the blockchain/cryptocurrency community exists on Twitter. Having your proposal in the deposit period is a good time to engage the so-called 'crypto Twitter' Cosmos community to prepare validators to vote (eg. tag [@cosmosvalidator](https://twitter.com/cosmosvalidator)) and ATOM-holders that are staking (eg. tag [@cosmos](https://twitter.com/cosmos), [@adriana_kalpa](https://twitter.com/adriana_kalpa)). 
 
 ### The Voting Period
+
 At this point you'll want to track which validator has voted and which has not. You'll want to re-engage directly with top stake-holders, ie. the highest-ranking validator operators, to ensure that:
 1. they are aware of your proposal;
 2. they can ask you any questions about your proposal; and