Problem: Docs re contributing needed editing & reorg

Solution: Edit & reorg them

.github/CONTRIBUTING.md

@@ -2,6 +2,6 @@
 
 There are many ways you can contribute to the BigchainDB project, some very easy and others more involved.
 
-All of that is documented elsewhere: go to the "[Contributing to BigchainDB" docs on ReadTheDocs](https://docs.bigchaindb.com/en/latest/). Note: that link goes to the root docs, but you can click from there to get to the "Contributing to BigchainDB" docs, once they get published on ReadTheDocs.
+All of that is documented elsewhere: go to the "[Contributing to BigchainDB" docs on ReadTheDocs](https://docs.bigchaindb.com/projects/contributing/en/latest/index.html).
 
 Note: GitHub automatically links to this file (`.github/CONTRIBUTING.md`) when a contributor creates a new issue or pull request, so you shouldn't delete it. Just use it to point people to full and proper help elsewhere.

.github/ISSUE_TEMPLATE.md

@@ -1,20 +1,19 @@
-You can create a new issue but it must be a proper and complete bug report. Nothing else is a valid issue. See the "Issue Rules" in the docs about "Contributing to BigchainDB". A link is coming soon. For now, go to:
+# Do you want to:
 
-https://docs.bigchaindb.com/en/latest/
+- make a bug report? Then read below about what should go in a bug report.
+- make a feature request or proposal? Then read [the page about how to make a feature request or proposal](https://docs.bigchaindb.com/projects/contributing/en/latest/ways-can-contribute/make-a-feature-request-or-proposal.html).
+- ask a question about BigchainDB? Then [go to Gitter](https://gitter.im/bigchaindb/bigchaindb) (our chat room) and ask it there.
+- share your neat idea or realization? Then [go to Gitter](https://gitter.im/bigchaindb/bigchaindb) (our chat room) and share it there.
 
-and follow the links from there.
+# What Should Go in a Bug Report
 
-Describe everything in detail:
-
-+ What computer are you on (hardware)?
-+ What operating system are you using, including version. e.g. Ubuntu 14.04? Fedora 23? If it's not a Linux distro, then that's probably the problem.
-+ What version of BigchainDB software were you using? Did you update it to the latest?
-+ What, exactly, did you do to get to the point where you got stuck? Describe all the steps so we can get there too.
-+ Show screenshots or copy-and-paste text to GitHub
-+ Say what you expected to happen
-+ Show what actually happened
-+ Say what you tried to do to resolve the problem
-+ Provide details to convince us that it matters to you. Is it for a school project, a job, a contract with a deadline, a child who needs it for Christmas?
+- What computer are you on (hardware)?
+- What operating system are you using, including version. e.g. Ubuntu 14.04? Fedora 23?
+- What version of BigchainDB software were you using? Is that the latest version?
+- What, exactly, did you do to get to the point where you got stuck? Describe all the steps so we can get there too. Show screenshots or copy-and-paste text to GitHub.
+- Show what actually happened.
+- Say what you tried to do to resolve the problem.
+- Provide details to convince us that it matters to you. Is it for a school project, a job, a contract with a deadline, a child who needs it for Christmas?
 
 We will do our best but please understand that we don't have time to help everyone, especially people who don't care to help us help them. "It doesn't work." is not going to get any reaction from us. We need _details_.
 

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,5 +1,18 @@
-There are very few valid reasons to create a pull request. To learn what they are (e.g. a BEP, or a short & specific solution to a well-defined problem), and how to structure the pull request, see the BigchainDB docs about "Contributing to BigchainDB". A link is coming soon. For now, go to:
+Make sure the title of this pull request has the form:
 
-https://docs.bigchaindb.com/en/latest/
+**Problem: A short statement of the problem.**
 
-and follow the links from there.
+## Solution
+
+A short statement about how this PR solves the **Problem**.
+
+## Issues Resolved
+
+What issues does this PR resolve, if any? Please include lines like the following (i.e. "Resolves #NNNN), so that when this PR gets merged, GitHub will automatically close those issues.
+
+Resolves #NNNN
+Resolves #MMMM
+
+## BEPs Implemented
+
+What [BEPs](https://github.com/bigchaindb/beps) does this pull request implement, if any?

docs/contributing/source/cross-project-policies/release-process.md

@@ -1,13 +1,5 @@
 # Our Release Process
 
-## Notes
-
-This process hasn't been updated to the C4 way yet. That will simplify it a lot. Stay tuned! Until then, the basic idea is that there's only one branch: `master`. All releases are just Git tags of specific commits on the `master` branch.
-
-This is the _BigchainDB Server_ release process. The process to release other BigchainDB software will be similar but not identical.
-
-<hr>
-
 The release process for BigchainDB server differs slightly depending on whether it's a minor or a patch release.
 
 BigchainDB follows 

docs/contributing/source/cross-project-policies/shared-workspace.md

@@ -1,28 +1,34 @@
 # Shared Workspace Protocol
-![raw](http://rfc.unprotocols.org/spec:2/COSS/raw.svg)
-
-- Name: Shared Workspace Protocol
-- Status: raw
-- Editor: Alberto Granzotto <alberto@bigchaindb.com>
+```
+shortname: 6/SWP
+name: Shared Workspace Protocol
+type: Meta
+status: Draft
+editor: Alberto Granzotto <alberto@bigchaindb.com>
+```
 
 ## Abstract
-Focusing in a shared workspace (or in the office in general) can be a really challenging task. Working from home solves the problem, but it is not an ideal solution if forced by the difficulty to focus in the office.
+The "Shared Workspace Protocol" provides a simple set of rules for people working in the same workspace.
 
-The "Shared Workspace Protocol" ("SWP" henceforth) provides a simple set of rules for people working in the same workspace.
+## Motivation
+Focusing in a shared workspace (or in the office in general) can be a really challenging task. Working from home solves the problem, but it is not an ideal solution if forced by the difficulty to focus in the office.
 
 ## Language
 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://tools.ietf.org/html/bcp14) \[[RFC2119](https://tools.ietf.org/html/rfc2119)\] \[[RFC8174](https://tools.ietf.org/html/rfc8174)\] when, and only when, they appear in all capitals, as shown here.
 
-## Goals
+## Rationale
 SWP provides a reusable collaboration model for people working in the same workspace. It has these specific goals:
 
 1. To maximize focus and productivity, by reducing the sources of distraction.
 1. To reduce the burden to ask people to "behave" or "leave the room", by having an explicit protocol people agree before entering the room.
 
-## Design
+## Implementation
 1. When implemented, this protocol MUST be visible at the entrance of the shared workspace.
 1. A person SHOULD write a message to another person before speaking with them.
 1. A person SHOULD NOT be loud.
 1. A person SHOULD NOT talk to more than one person at a time.
 1. One-on-one conversations MUST be short and occasional.
 1. A person MUST NOT have calls unless everyone in the room is involved.
+
+## Copyright Waiver
+To the extent possible under law, the person who associated CC0 with this work has waived all copyright and related or neighboring rights to this work.

docs/contributing/source/dev-setup-coding-and-contribution-process/index.rst

@@ -0,0 +1,9 @@
+Developer Setup, Coding & Contribution Process
+==============================================
+
+.. toctree::
+   :maxdepth: 2
+
+   setup-dev-environment
+   write-code
+   vanshdeep-notes

docs/contributing/source/dev-setup-coding-and-contribution-process/vanshdeep-notes.md

@@ -128,7 +128,7 @@ $ pip install -e .[dev]  #  or  pip install -e '.[dev]'  # for zsh
 ```
 
 
-## Running tests
+## Running All Tests
 
 To execute tests when developing a feature or fixing a bug one could use the following command,
 

docs/contributing/source/dev-setup-coding-and-contribution-process/write-code.rst

@@ -1,12 +1,14 @@
 Write Code
 ==========
 
-What are you Doing???
----------------------
+Know What You Want to Write Code to Do
+--------------------------------------
 
-Tell us what you're doing somewhere so we don't do it too. You can tell us on Gitter or by email.
-If you're not sure how to proceed, see the :ref:`Issue Rules` and :ref:`Write a BEP <Write a BigchaindB Enhancement Proposal (BEP)>`
-for inspiration.
+Do you want to write code to resolve an open issue (bug)? Which one?
+
+Do you want to implement a BigchainDB Enhancement Proposal (BEP)? Which one?
+
+You should know why you want to write code before you go any farther.
 
 
 Refresh Yourself about the C4 Process

docs/contributing/source/index.rst

@@ -17,5 +17,6 @@ Contents
 .. toctree::
    :maxdepth: 2
 
+   ways-to-contribute/index
+   dev-setup-coding-and-contribution-process/index
    cross-project-policies/index
-   ways-can-contribute/index

docs/contributing/source/ways-can-contribute/issue-rules.md

@@ -1,44 +0,0 @@
-# Issue Rules
-
-## Bad Issues Are Things Like This
-
-We would be very sad to see you make an issue that is:
-
-- Your latest brain fart.
-- An idea you had to maybe do in two years.
-- "Consider this..."
-- Something nobody really cares about, not even you.
-- Showing off your knowledge and understanding of something.
-- A "feature request." Make a [BEP](write-a-bep.html) for that. Or a small pull request with a well-defined _problem_ and _solution_ as desribed in C4. If you really _want_ something, make it happen! Don't try to trick others into thinking your idea is "interesting." Get the ball rolling.
-- A proposal of any length. Write a BEP.
-
-If you do any of the above, we will just delete your issue. We don't have time for a long cluttered list of issues.
-
-
-## Good Issues Are Bug Reports
-
-There is one good issue type: a proper bug report.
-
-1. Go to the repository with the source code for the bug. Possibilities include:
-
-   - [BigchainDB Server](https://github.com/bigchaindb/bigchaindb)
-   - [BigchainDB Python Driver](https://github.com/bigchaindb/bigchaindb-driver)
-   - [BigchainDB JavaScript Driver](https://github.com/bigchaindb/js-bigchaindb-driver)
-   - [cryptoconditions](https://github.com/bigchaindb/cryptoconditions) (a Python package by us)
-   - [py-abci](https://github.com/davebryson/py-abci) (a Python package we use)
-
-1. Click on the **Issues** tab.
-1. Click the button to create a **New Issue**.
-1. Describe everything in detail:
-
-   - What computer are you on (hardware)
-   - What operating system are you using, including version. e.g. Ubuntu 14.04? Fedora 23? If it's not a Linux distro, then that's probably the problem.
-   - What version of BigchainDB software were you using? Did you update it to the latest?
-   - What, exactly, did you do to get to the point where you got stuck? Describe all the steps so we can get there too.
-   - Show screenshots or copy-and-paste text to GitHub
-   - Say what you expected to happen
-   - Show what actually happened
-   - Say what you tried to do to resolve the problem
-   - Provide details to convince us that it matters to you. Is it for a school project, a job, a contract with a deadline, a child who needs it for Christmas?
-
-We will do our best but please understand that we don't have time to help everyone, especially people who don't care to help us help them. "It doesn't work." is not going to get any reaction from us. We need _details_.

docs/contributing/source/ways-can-contribute/write-a-bep.md

@@ -1,18 +0,0 @@
-# Write a BigchaindB Enhancement Proposal (BEP)
-
-This is the main way to get new BigchainDB code into the project.
-
-There are two general paths:
-
-1. Create a BEP. Then create a pull request to implement it. And so on.
-1. Create a new pull request straight away. This is less likely to work. It is only going to be permitted if the problem being solved is clear, obvious, small and well-defined in the pull request. If it's not, then a BEP was needed and you need to go back and write a BEP first.
-
-
-## Tips
-
-- Review [1/C4](https://github.com/bigchaindb/BEPs/tree/master/1), the process we use to accept any new code or PR of any kind, including one that adds a BEP to `bigchaindb/BEPs`.
-- Review [2/COSS](https://github.com/bigchaindb/BEPs/tree/master/2). Maybe print it for reference. It outlines what can go in a BEP.
-- Don't spend weeks on your BEP. Version 1 should take a few hours to write up, maximum. You can add to it in the future. The process is iterative. If you need more than a few hours, then consider writing multiple BEPs.
-- Do not start writing code before you think about it. You should always write a BEP first. Once you do that, you _can_ start implementing it. To do that, make a pull request and say it implements your BEP.
-- If you're thinking of writing a new _issue_, think again. See the page [Issue Rules](issue-rules.html).
-

docs/contributing/source/ways-to-contribute/index.rst

@@ -1,15 +1,12 @@
 Ways to Contribute
 ==================
 
-
-
 .. toctree::
    :maxdepth: 1
 
-   issue-rules
+   report-a-bug
+   write-an-issue
+   make-a-feature-request-or-proposal
    write-a-bep
-   setup-dev-environment
-   write-code
-   vanshdeep-notes
    write-docs
    answer-questions

docs/contributing/source/ways-to-contribute/make-a-feature-request-or-proposal.md

@@ -0,0 +1,3 @@
+# Make a Feature Request or Proposal
+
+To make a feature request or proposal, [write a BigchainDB Enhancement Proposal (BEP)](write-a-bep.html).

docs/contributing/source/ways-to-contribute/report-a-bug.md

@@ -0,0 +1,3 @@
+# Report a Bug
+
+To report a bug, go to the relevant GitHub repository, click on the **Issues** tab, click on the **New issue** button, and read the instructions.

docs/contributing/source/ways-to-contribute/write-a-bep.md

@@ -0,0 +1,7 @@
+# Write a BigchaindB Enhancement Proposal (BEP)
+
+- Review [1/C4](https://github.com/bigchaindb/BEPs/tree/master/1), the process we use to accept any new code or PR of any kind, including one that adds a BEP to `bigchaindb/BEPs`.
+- Review [2/COSS](https://github.com/bigchaindb/BEPs/tree/master/2). Maybe print it for reference. It outlines what can go in a BEP.
+- Don't spend weeks on your BEP. Version 1 should take up to a few hours to write. You can add to it in the future. The process is iterative. If you need more than a few hours, then consider writing multiple BEPs.
+- Do _not_ start writing code before you think about it. You should always write a BEP first. Once you do that, you can start implementing it. To do that, make a pull request and say it implements your BEP.
+- Do _not_ write your BEP as an issue (i.e. a GitHub issue).

docs/contributing/source/ways-to-contribute/write-an-issue.md

@@ -0,0 +1,3 @@
+# Write an Issue
+
+To write an issue, go to the relevant GitHub repository, click on the **Issues** tab, click on the **New issue** button, and read the instructions.