Merge pull request #3270 from dfinity/updateNNSdocs

Update NNS dev docs

docs/developer-docs/daos/nns/neurons-fund.mdx → docs/developer-docs/daos/nns/concepts/neurons-fund.mdx

@@ -1,5 +1,5 @@
 ---
-keywords: [intermediate, governance, concept, nns]
+keywords: [intermediate, governance, concept, nns, neurons fund, neurons, NF]
 ---
 
 

docs/developer-docs/daos/nns/proposal-voting.mdx → docs/developer-docs/daos/nns/concepts/neurons/becoming-a-known-neuron.mdx

@@ -1,102 +1,77 @@
 ---
-keywords: [intermediate, governance, concept, nns]
+keywords: [advanced, governance, tutorial, nns, known neurons, named neurons, neurons]
 ---
 
 import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";
+import '/src/components/CenterImages/center.scss';
 
-# Voting on proposals
+# Registering a known neuron
 
-<MarkdownChipRow labels={["Intermediate", "Governance", "Concept"]} />
+<MarkdownChipRow labels={["Advanced", "Governance", "Tutorial"]} />
 
 ## Overview
-The NNS DAO is an open governance system where anyone can become a participant by [staking some ICP in a neuron](https://internetcomputer.org/docs/current/developer-docs/daos/nns/nns-app-quickstart#stake-icp-utility-tokens-in-a-neuron) and locking the tokens for at least 6 months. Locking tokens for a period of time is known as the neuron's dissolve delay.
-
-## Finding proposals and discussions
-
-You can see all the NNS proposals on the [Internet Computer dashboard](https://dashboard.internetcomputer.org/governance) or on the [NNS dapp](https://nns.ic0.app/). Voters can freely discuss proposals anywhere they like. A lot of NNS proposals are discussed on the [developer forum](https://forum.dfinity.org/c/roadmap/29).
-
-## Direct voting
-When a user has an eligible neuron and would like to vote on an open proposal, one option is to directly vote to adopt or reject the proposal. Currently, the most user-friendly way to first find and [vote on open proposals](/docs/current/developer-docs/daos/nns/nns-app-quickstart#vote-on-proposals) is via the NNS Frontend dapp: https://nns.ic0.app/.
-
-## Liquid democracy (following)
-Users may not have the time or knowledge to participate in all voting decisions. Therefore, instead of directly voting on proposals, neuron holders may choose to delegate their vote to other neurons that they trust with certain decisions. This concept of delegating the right to vote to other neurons, who then effectively vote with more voting power, is called **liquid democracy**. In the NNS DAO, this is also called **following**, as a neuron follows the decision of some other neurons.
-
-### How to follow a neuron
-Concretely, proposals are grouped into different [**proposal topics**](./proposal-voting.mdx#proposal-topics-and-types) and following is done on a per-topic basis. Learn how you can set up your neuron to [follow a group of other neurons](/docs/current/developer-docs/daos/nns/nns-app-quickstart#neuron-following).
+A know neuron has a name and optionally a short description.
+A known neuron can be registered in the NNS governance via a proposal, officially storing its name and description
+within the NNS. This information can be used by other neurons to find known neurons and [follow](/docs/current/developer-docs/daos/nns/concepts/neurons/neuron-following) them.
 
-### How to find neurons to follow
-In order for a neuron to follow others, there need to be some neurons that actively vote and can be followed.
+To become a known neuron in the NNS DAO, you first need to create a neuron, then submit an NNS proposal to register as a known neuron. After the proposal is accepted and your neuron is registered, it will be visible to all NNS users when they set up their own neuron following.
 
-There are two ways neurons to follow can be found and set:
-* A user with an actively voting neuron who is offering to be followed can communicate their neuron ID to others, for example on the forum or their website. Other neurons can then [follow them](https://internetcomputer.org/docs/current/developer-docs/daos/nns/nns-app-quickstart#step-5-enter-a-neuron-id-to-follow-or-select-a-group-of-neurons-from-the-menu-provided) using this neuron ID.
-* A user with an actively voting neuron who is offering to be followed can register a **known neuron**, also called a **named neuron**, in the NNS governance canister. Neurons who would like to follow others can see a list of all registered neurons with their name and optionally a short description, and can then select one of them to follow (without having to remember an ID).
+It can be useful for known neuron candidates to be an (unregistered) actively voting neuron for a while before registering a neuron. During this time, the neuron holder can get familiar with voting and start becoming an expert in a topic. They can also share their neuron ID for others to follow them. In this way, by the time that they register the neuron as a known neuron, there is already some evidence of their voting behavior that NNS participants can base their decision on. Moreover, to convince the NNS DAO to accept a new known neuron, it can be useful for known neuron candidates to present themselves to the community outside the governance context, for example, on the forum or social media.
 
-## How to become a known neuron
-To become a known neuron in the NNS DAO, you first need to create a neuron and then submit an NNS proposal to register the known neuron in the NNS governance.
-A know neuron has a name and optionally a short description.
-After registering the known neuron, it will be visible to all NNS DAO users when they set up their following.
-It can be useful for known neuron candidates to be an (unregistered) acvitely voting neuron for a while before registering the neuron.
-During this time, the neuron holder can get familiar with voting and start becoming an expert in a topic. They can also alread share their neuron ID for others to follow them.
-In this way, by the time that they register the neuron as a known neuron, there is already some evidence of their behavior as voters that NNS voters can base their decision on.
-Moreover, to convince the NNS DAO to accept a new known neuron, it can be useful for known neuron candidates to present themselves to the community outside the governance context, for example on the forum or social media.
-
-### Create a neuron
-There are multiple options to create and set up a neuron that is then registered as a know neuron.
-A known neuron can be operated by an individual person or an organization where one person controls the neuron
-or it can be operated by a group of people.
+## Create a neuron
+There are multiple options to create and set up a neuron that can then be registered as a know neuron.
+A known neuron can be operated by an individual person, or an organization where either one person controls the neuron or it is operated by a group of people.
 Depending on this, different neuron creation options might be more suitable.
 
-#### Create a neuron controlled by one party
+### Create a neuron controlled by one party
 
 If you would like to create a known neuron that is operated by one party that knows the neuron's controlling key and can change the neuron, you can use one of the following options:
-* [Create the neuron on the NNS dapp](/docs/current/developer-docs/daos/nns/nns-app-quickstart#stake-icp-utility-tokens-in-a-neuron).
+* [Create the neuron on the NNS dapp](/docs/current/developer-docs/daos/nns/using-the-nns-dapp/nns-app-quickstart#stake-icp-utility-tokens-in-a-neuron).
 * [Create the neuron on the NNS dapp that is controlled by a hardware ledger wallet](https://support.dfinity.org/hc/en-us/articles/8760495850900-How-do-I-use-my-Ledger-Nano-with-the-Internet-Computer)
 * [Create the neuron via the quill command line tool](https://support.dfinity.org/hc/en-us/articles/4408752586260-What-is-Quill).
 
 :::info
-If there are multiple people involved in a know neuron's voting decision, the known neuron can be set up to follow their individual neurons
- on the topics that it should vote on.
-However, for a neuron which is created this way, the **person who created the neuron has the controlling key**.
-This person can modify the neuron and, in particular, can also vote in the name of the neuron without taking the input of others into account.
+If there are multiple people involved in a known neuron's voting decision, the known neuron can be set up to follow their individual neurons on the topics that it should vote on.
+However, for a neuron that is created this way, the **person who created the neuron has the controlling key**.
+This person can modify the neuron and, in particular, can also vote using the neuron without taking the input of others into account.
 This can be suitable for individuals who operate a known neuron, or for organizations where one person is trusted with this task.
-
 :::
 
-#### Create a community neuron
+### Create a community neuron
 
 Additional information on how to create a community neuron will be added soon!
 
 
-### Start voting and present your neuron to the community
+## Start voting and present your neuron to the community
 Once you have created a neuron, you can start voting with it and also share context about how you voted and why with the community. You can already share your neuron ID with others so that they can follow you on certain topics.
 
-When you are familiar with voting and soon ready to register a know neuron, you can prepare for this step. A known neuron needs a name and a description. Often, the owners of known neurons use the description part to present themselves to the community.
-
 There are no rules that a known neuron must follow regarding if it presents itself to the community or not, but it can make sense for neuron owners to present themselves before submitting the proposal to register themselves as a known neuron. This can serve as a way for promoting the neuron and explaining the motivation behind it.
 This can, for example, be done with a forum post or by sharing information on social media, such as OpenChat or X.
-It might be useful to share the following information with the community, so that followers can make well-informed decisions regarding who to follow for which topic:
-* **Who you are**: Name of the person or group and their relationship to the ICP. You may want to argue why the people behind the neuron have a long-term interest in the wellbeing of the ICP and are, therefore, motivated to make good voting decisions.
-* **Neuron control**: Who controls the neuron? Does it have a single controller or can it only be changed by a group of people?
+
+This might be useful so that followers can make well-informed decisions regarding who to follow for which topic:
+
+* **Who you are**: Name of the person or group and their relationship to the ICP. You may want to argue why the people behind the neuron have a long-term interest in the wellbeing of the ICP and are motivated to make good voting decisions.
+* **Neuron control**: Who controls the neuron? Does it have a single controller or can it be changed by a group of people?
 * **Covered topics**: A description of what topics the known neuron will vote on. Does the neuron commit to always vote on these topics? Since following is done based on proposal topics, this is relevant information for followers. Usually, neurons would want to follow other neurons that always vote on a given topic in order not to miss out on [voting rewards](./staking-voting-rewards.mdx).
 * **Depth of reviews**: A description of how the known neuron plans to verify proposals. To which depth will it review the code or the content of the proposal and how is this done?
 * **Following setting**: For the topics where the know neuron does not vote directly, who does the neuron follow?
 * **Voting principles**: What are the principles according to which you plan to vote?
-* **Link to the neuron ID / proposal**: If you already created the neuron, you may want to provide its ID or even link to a dashboard where it can be inspected. The same holds for the proposal to register it as a know neuron in the case where the proposal was already made.
+* **Link to the neuron ID / proposal**: If you already created the neuron, you may want to provide its ID or even link to a dashboard where it can be inspected. The same holds for the proposal to register it as a known neuron in the case where the proposal was already made.
 
 :::info
-There are no rules regarding how a known neuron has to vote. However, due to the above reasons, it might be useful for known neurons to **focus on fewer topics and commit to always vote on those** rather than trying to cover a lot of topics and vote less reliably. For example, they could become experts on some proposal topics. If a known neuron commits to always vote on a certain topic, it might be more likely that others follow the neuron on this topic as the followers want to make sure they are not missing out on rewards.
-
+It might be useful for known neurons to **focus on fewer topics and commit to always vote on those** rather than trying to cover a lot of topics and vote less reliably. For example, they could become experts on some proposal topics. If a known neuron commits to always vote on a certain topic, it might be more likely that others follow the neuron on this topic as the followers want to make sure they are not missing out on rewards.
 :::
 
 
-### Register the known neuron
+## Register the known neuron
 To register a neuron as a know neuron, you need to submit a NNS proposal. The proposal can be submitted by any neuron that has at
 least 10 ICP staked.
 For simplicity, we assume in the following example that the neuron to be registered was created on the NNS dapp and that the same neuron is
 used to submit the proposal.
 
-**1. Download and install `dfx`**
-It is not possible to submit proposals through the NNS dapp. Therefore, you must use a command line tool called `dfx`.`dfx` is only natively supported on Mac and Linux, but it can be installed on Windows using WSL. 
+- ### Step 1: Download and install `dfx`
+
+It is not possible to submit proposals through the NNS dapp. Therefore, you must use a command line tool called `dfx`.`dfx` is only natively supported on Mac and Linux, but it can be installed on Windows using WSL.
 
 To install `dfx`, follow the [installation instructions](/docs/current/developer-docs/getting-started/install/#installing-dfx).
 
@@ -109,11 +84,12 @@ sh -ci "$(curl -fsSL https://internetcomputer.org/install.sh)"
 If you are using a machine running Apple silicon, you will need to have [Rosetta](https://support.apple.com/en-us/HT211861) installed.
 You can install Rosetta by running `softwareupdate --install-rosetta` in your terminal.
 
-**2. Add your `dfx` principal as a hotkey to your neuron**
+- ### Step 2: Add your `dfx` principal as a hotkey to your neuron
+
 Your neuron is controlled by a **principal ID**, which is an identity on ICP.
 However, you want to be able to submit proposals from the command line on your computer in this neuron's name.
 For this, you can register the principal that you have on your computer as a
-[**hot key**](/docs/current/developer-docs/daos/nns/neuron-management#neuron-attributes)
+[**hot key**](/docs/current/developer-docs/daos/nns/concepts/neurons/neuron-management#neuron-attributes)
 of the neuron. Hot keys have the permission to vote and submit proposals for the neuron.
 
 Run `dfx identity get-principal` to get the principal ID that corresponds to your current [developer identity](/docs/current/developer-docs/getting-started/accounts). The following steps will refer to this as your "dfx principal".
@@ -125,7 +101,7 @@ and press confirm.
 Your dfx principal should appear under “Hotkeys”.
 You can now control your neuron from the local terminal.
 
-**3. Submit the proposal**
+- ### Step 3: Submit the proposal
 To submit the proposal, you need the neuron ID of the neuron to be registered as a known neuron, a name for the known neuron, and a
  short description.
  You find your neuron ID in the NNS dapp at the top right of the NNS dashboard page for your neuron.