Produce 'Roles' doc

proposals.adoc

@@ -1,51 +1,71 @@
 = Proposals
 
-Proposals are a means for suggesting specific changes to Bisq Network software components, infrastructure and processes. They are especially useful where awareness and agreement of other contributors is required in order for the change to be successfully implemented.
+Proposals are a means for suggesting changes to Bisq Network software components, infrastructure and processes.
 
 
 == Introduction
 
-The Bisq DAO is a flat organization, meaning that there is no command-and-control hierarchy available to make big decisions and carry them out.
+The Bisq DAO is a flat organization, with no command-and-control hierarchy available to make big decisions and carry them out. Usually this is not a problem, as most day-to-day changes happen without any need for organization-wide consensus. Certain kinds of changes, however, benefit from or even require it.
 
-Generally, this is not a problem, as the Bisq DAO is designed for contributors to operate permissionlessly and autonomously. Most day-to-day changes happen without any need for organization-wide consensus, but there are certain kinds of changes that benefit from or even require it. For such cases, what's needed is a mechanism that allows any contributor to _propose_ a change, and allows any and all other contributors to _review_ it in order to arrive at an IETF-style https://en.wikipedia.org/wiki/Rough_consensus[rough consensus] whether to proceed.
-
-_Proposals_ are that mechanism within the Bisq DAO, and this document covers everything that submitters, reviewers and maintainers need to know about the infrastructure, process and best practices around them.
+What's needed is a mechanism that allows any contributor to _propose_ a change, and all other contributors to _review_ it in order to arrive at an IETF-style rough consensus.footnote:[See link:https://en.wikipedia.org/wiki/Rough_consensus[]] _Proposals_ are that mechanism, and this document covers everything that participants need to know about the process.
 
 === What proposals are good for
 
-If you're thinking of creating an entire new Bisq component or making a significant change to an existing one, it's a good idea to submit a proposal first. Likewise, if you want to change something about the way contributors work together under the Bisq DAO, submit a proposal.
+ * Creating an entire new Bisq component or making a significant change to an existing one
+ * Changing something about the way contributors work together
 
 === What proposals are not good for
 
-For smaller changes to existing components, infrastructure or processes, where a broad consensus of contributors is not required, just submit an issue and/or pull request in the relevant repository. The maintainer of that repository will let you know if the change is too big or controversial, in which case they'll probably suggest you write a proposal. When in doubt, don't jump right to submitting a proposal. Have a conversation first. Chat with other contributors. See if they think a proposal is merited.
+ * Smaller changes to existing components, infrastructure or processes, where a broad consensus of contributors is not required
 
 
 == Infrastructure
 
 === GitHub
 
-Proposals are managed as GitHub issues in the https://github.com/bisq-network/proposals/issues[bisq-network/proposals] repository.
-
-TIP: If you're an active Bisq contributor, consider https://help.github.com/articles/watching-and-unwatching-repositories/[watching] this repository to be notified of new proposals and discussions around them. You can always https://help.github.com/articles/subscribing-to-and-unsubscribing-from-notifications/[unsubscribe] from specific issues you're not interested in.
+Proposals are managed as GitHub issues in the {gh-org}/proposals/issues[bisq-network/proposals] repository.
 
 === Slack
 
 The `#proposals` Slack channel is available for discussion and notifications about proposal issue activity.
 
 
-== Roles and responsibilities
+== Roles
 
 === Submitter
 
-The contributor(s) who write a proposal and carry it through to completion. **Submitters are 100% responsible for the success of their proposals.**
+The contributor(s) who write a proposal and carry it through to completion.
+
+**Submitters are 100% responsible for the success of their proposals.**
 
 === Reviewer
 
-Other contributors who read, discuss and react to proposals. **Any contributor _may_ review a proposal, but no contributor is obligated to do so.** This intentionally puts the onus on the submitter to ensure their proposal is relevant and well-written per the guidelines below.
+Other contributors who read, discuss and react to proposals.
+
+**Any contributor _may_ review a proposal, but no contributor is obligated to do so.** This intentionally puts the onus on the submitter to ensure their proposal is relevant and well-written per the <<guidelines>> below.
 
 === Maintainer
 
-The contributor(s) who have administrative rights over the `bisq-network/proposals` GitHub repository, monitor the `#proposals` Slack channel, enforce the process detailed below, and write https://github.com/bisq-network/roles/issues/30[monthly reports] on proposals activity. **Maintainers have no special authority to approve or reject proposals.**
+The contributor(s) responsible for proposals <<infrastructure>> and <<process>>.footnote:[See link:roles.html#maintainer[]]
+
+==== Role Issue
+
+{gh-org}/roles/issues/30[#30]
+
+==== Duties
+
+ * Enforce the proposals <<process>> detailed below.
+ * Monitor communications on the `#proposals` Slack channel.footnote:[See link:roles.html#communication[]]
+ * Keep this proposals documentation up to date.footnote:[See link:roles.html#documentation[]]
+ * Write a monthly report on the proposals maintainer <<role-issue>>.footnote:[See link:roles.html#reporting[]]
+
+==== Rights
+
+ * Write access to the {gh-org}/proposals[bisq-network/proposals] repository
+
+==== Owners
+
+See the <<role-issue>>
 
 
 == Process
@@ -67,7 +87,7 @@ A maintainer will quickly review your proposal and will either (a) assign it to
 
 === Step 2. Review
 
-Once a proposal is submitted, a two-week review period follows. During this period, interested reviewers should read, discuss and ultimately react to the proposal as follows:
+Once a proposal is submitted, a two-week review period follows. During this period, interested reviewers should read, discuss and ultimately https://help.github.com/articles/about-conversations-on-github/#reacting-to-ideas-in-comments[react] to the proposal as follows:
 
  - 👍: I agree with the proposal and want to see it enacted
  - 😕: I am uncertain about the proposal and I need more information
@@ -79,7 +99,7 @@ If you do not understand or care about a given proposal, ignore it.
 
 Use comments on the proposal issue to discuss, ask questions, and get clarifications. Take lengthy discussions offline to Slack or elsewhere and then summarize them back on the issue.
 
-TIP: Remember that the proposal review process is all about reaching a _rough consensus,_ meaning that there is a broad agreement that the proposal should be enacted, and that any dissenting opinions have been addressed, though not necessarily fully resolved.
+NOTE: Remember that the proposal review process is all about reaching a _rough consensus,_ meaning that there is a broad agreement that the proposal should be enacted, and that any dissenting opinions have been addressed, though not necessarily fully resolved.
 
 === Step 3. Evaluate
 

roles.adoc

@@ -1,25 +1,50 @@
-= Roles
+= Bisq DAO Roles
 
-Roles are the means by which responsibility over specific Bisq Network components, infrastructure and processes is delegated to individual contributors.
+Roles are the way contributors take responsibility for Bisq Network resources and processes.
 
 
 == Introduction
 
-The Bisq DAO is a flat organization, without traditional management or reporting structures. At the same time, there are many vital resources and processes that must be cared for by individuals. For example, someone must manage the DNS for the https://bisq.network[bisq.network] domain, someone must admininister the {gh-org}[bisq-network] GitHub organization, and so on.
+The Bisq DAO is a flat organization, without traditional management or reporting structures. At the same time, there are many vital resources and processes that must be cared for by individuals. For example, someone must manage the DNS for the `bisq.network` domain, someone must conduct monthly stakeholder voting, and so on.
 
-And because the Bisq DAO is not a volunteer organization, but one that compensates valuable contributions, it must be possible for stakeholders to assess how these resources and processes are being cared for over time so as to know whether and how much to compensate those in charge of them.
+What's needed is a mechanism that defines these various duties, makes it clear who is responsible for each, and that includes a process for regular reporting and feedback. The system of _roles_ described below provides such a mechanism.
 
-What's needed is a mechanism that defines each of these responsibilities, makes it clear who is responsible for them, and that includes a process for regular reporting and feedback. The system of roles described below provide that mechanism.
+
+[[characteristics]]
+== Characteristics of a role
+
+=== Duties
+
+Actions that must be performed for a certain resource or process to function normally.
+
+For example, a repository maintainer's duties include merging pull requests in a timely fashion, and the website operator's duties include keeping the site available at all times.
+
+=== Rights
+
+Special permissions or other access required to perform the <<duties>> of a role.
+
+For example, a repository maintainer's rights include write permissions to their repository, and the website operator's rights include administrative access to site hosting infrastructure.
+
+=== Owners
+
+Contributors who have the <<rights>> required to perform the <<duties>> of a role.
+
+One owner is designated as _primary_ and any other owners are designated as _secondary_.footnote:[See {gh-org}/proposals/issues/12] The primary is responsible for performing the <<duties>> of the role, while secondaries stand by, capable of taking over for the primary at any time.
 
 
 == Infrastructure
 
+=== Docs
+
+There is no "role documentation" per se, but rather there is documentation about whatever component or infrastructure a given role is responsible for, and in that documentation, there is a section for the role.
+
 === GitHub
 
 ==== Issues
 
 Roles are managed as issues in the {gh-org}/roles/issues[bisq-network/roles] repository.
 
+////
  - Assignees used to track role ownership
  - Description field used to
    - Link to team
@@ -31,33 +56,26 @@ Roles are managed as issues in the {gh-org}/roles/issues[bisq-network/roles] rep
  - Anyone can subscribe to any issue or watch the whole repo to stay up to date with reporting
  - Labels used to
    - Indicate `help wanted`
+////
 
 ==== Teams
 
 Managed as GitHub Teams. For @mentions and to institutionalize thinking in terms of roles not individuals.
 
-=== Docs
-
-There is no "role documentation" per se, but rather there is documentation about whatever component or infrastructure a given role is responsible for, and in that documentation, there is a section for the role.
-
 === Slack
 
 Slack.
 
 
-== Anatomy of a role
+== Types
 
-=== Duties
-
-A role's _duties_ are the activities that the role's owner must carry out in order to be compensated for their efforts. For example, repository maintainers must enforce review process and merge pull requests in a timely fashion, the website operator must keep the site up and running at all times, and so forth.
-
-=== Rights
+=== Maintainer
 
-Most roles involve some special _rights,_ such as exclusive permissions or access to a given resource. For example, a maintainer of a bisq-network GitHub repository will have write permissions to that repository such that they can merge contributors' pull requests, the operator of the bisq.network website will have administrative access to the infrastructure that hosts the site, and so forth.
+=== Operator
 
-=== Owners
+=== Administrator
 
-Each role has one or more _owners,_ with one being designated as _primary_ and others being designated as _secondary_.footnote:[See {gh-org}/proposals/issues/12] The primary role owner is responsible for carrying out the day to day activities of that role, while secondary owners are standing by, fully capable of taking over for the primary owner in case of sickness or other incapacitation.
+=== Moderator
 
 
 == Common role duties
@@ -92,17 +110,6 @@ Generally means setting up notifications appropriately.
 Specifically, keeping your own role's documentation up to date
 
 
-== Common role types
-
-=== Maintainer
-
-=== Operator
-
-=== Administrator
-
-=== Moderator
-
-
 == Compensation
 
 
@@ -134,39 +141,3 @@ https://github.com/bisq-network/roles/issues/28
 All normal <<maintainter>>
 
 === Rights
-
-
-== Notes
-
-replace the proto-documentation we did for roles in the Phase Zero doc, particularly that found at docs.bisq.network/dao/phase-zero.html#bonded-contributor-roles
-
-capture the decisions we've made around roles in bisq-network/proposals#12 and bisq-network/proposals#13 and bisq-network/proposals#14
-
-document the way the bisq-network/roles repository works and document the responsibilities of the roles maintainer (bisq-network/roles#28).
-
-cover the relationship between role issues, GitHub teams, primary/secondary role owners
-
-document, or at least carve out a placeholder for documenting, the way bonding and BSQ interest payments will work for bonded contributor roles.
-
-document the process for creating a new role, which will likely involve submitting a proposal for a new role, similar to the way this one was done
-
-Update https://docs.bisq.network/dao/phase-zero.html#Appendix-A
-
-Close https://github.com/bisq-network/bisq-docs/issues/46
-
-Maintainer role must be fully separated from reviewer role. Maintainers validate that pull requests are correct, maintainers ensure that overall process is followed, maintainers give enough time for sufficient review, and then, maintainers merge pull requests. When somone is _reviewing_ a pull request, even if that person is a maintainer, they are not wearing their maintainer hat. They are wearing their _contributor_ hat. Maintainers do not review. See https://github.com/bisq-network/roles/issues/63#issuecomment-393453744 for counter-example of this. Reviewing puts too much on maintainers.
-
-////
-.Example
-----
-DNS Admin
-
-Assignees: @cbeams, @ripcurlx
-Description:
-    Team: @bisq-network/dns-admins
-    Primary: @cbeams
-    Docs: https://docs.bisq.network/dns.html#admin
-----
-////
-
-TIP: Subscribe to individual role issues or watch the entire repository to stay up to date with role reports.