diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md
index ba295fa1..95d86bf6 100644
--- a/.github/ISSUE_TEMPLATE.md
+++ b/.github/ISSUE_TEMPLATE.md
@@ -1,5 +1,23 @@
-Please include the following information in your ticket.
+Please [read these guidelines](http://ibm.biz/cdt-issue-guide) before opening an issue.
 
-- Cloudant (python-cloudant) version(s) that are affected by this issue.
-- Python version 
-- A small code sample that demonstrates the issue.
+<!-- Issues will be CLOSED IMMEDIATELY if the following template is not completed. -->
+
+## Bug Description
+
+### 1. Steps to reproduce and the simplest code sample possible to demonstrate the issue
+<!--
+Outline the steps you take to make the problem happen.
+Provide the simplest code sample you can, in context, that reproduces the issue.
+-->
+
+### 2. What you expected to happen
+
+### 3. What actually happened
+
+## Environment details
+<!--
+- Version(s) that are affected by this issue.
+    > 2.0.2
+- Python version
+    > 3.6.2
+-->
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index e80303d9..8a9c853a 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,23 +1,102 @@
+<!--
 Thanks for your hard work, please ensure all items are complete before opening.
+-->
+## Checklist
 
-- [ ] Tick to sign-off your agreement to the [Developer Certificate of Origin (DCO) 1.1](https://github.com/cloudant/python-cloudant/blob/master/DCO1.1.txt)
-- [ ] You have added tests for any code changes
-- [ ] You have updated the [CHANGES.md](https://github.com/cloudant/python-cloudant/blob/master/CHANGES.md)
-- [ ] You have completed the PR template below:
+- [ ] Tick to sign-off your agreement to the [Developer Certificate of Origin (DCO) 1.1](../blob/master/DCO1.1.txt)
+- [ ] Added tests for code changes _or_ test/build only changes
+- [ ] Updated the change log file (`CHANGES.md`|`CHANGELOG.md`) _or_ test/build only changes
+- [ ] Completed the PR template below:
 
-## What
+## Description
+<!--
+Provide a short description; saving the detail for the `Approach` section
 
-What was changed, e.g. Added support for querying views.
+Also EITHER:
+Link to issue this PR is resolving, use the Fixes #nnn form so that the
+issue closes automatically when the PR merges e.g.:
 
-## How
+Fixes #23
 
-How the change was implemented and reasoning behind it, e.g. Added create_index API to allow
-the creation of text and json indexes.
+OR
+
+For PRs without an associated issue and/or test/build issues
+
+### 1. Steps to reproduce and the simplest code sample possible to demonstrate the issue
+### 2. What you expected to happen
+### 3. What actually happened
+-->
+
+## Approach
+
+<!--
+Be brief: which component(s) of the code base does the fix focus on.
+
+A place to note whether the part of the code base that is being worked is
+particularly sensitive.
+-->
+
+## Schema & API Changes
+
+<!--
+EITHER:
+
+- "No change"
+
+OR
+
+For public API (as opposed to internal) changes
+
+- "Fixing bug in API, will change x in such-and-such way"
+-->
+
+## Security and Privacy
+
+<!--
+EITHER:
+
+- "No change"
+
+OR
+
+"Making changes in e.g. auth|https|encryption|io
+need to be careful about..."
+
+-->
 
 ## Testing
 
-How to test your changes work, not required for documentation changes.
+<!--
+EITHER:
+
+- Added new tests:
+    - test x
+    - test y
+    - test z
+
+OR
+
+- Modified existing tests because ...
+
+OR
+
+- N/A build or packaging only changes
+
+OR
+
+In exceptional circumstances there may be a good reason we can't add automated
+tests, for example if a specific device is required to reproduce a problem.
+
+- No new tests because...
+-->
+
+## Monitoring and Logging
+<!--
+EITHER:
+
+- "No change"
 
-## Issues
+OR
 
-Links to the github issue(s) (if present) that this pull request is resolving.
+- "Added new log line X..."
+-->
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..21890316
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,84 @@
+# Contributing
+
+## Issues
+
+Please [read these guidelines](http://ibm.biz/cdt-issue-guide) before opening an issue.
+If you still need to open an issue then we ask that you complete the template as
+fully as possible.
+
+## Pull requests
+
+We welcome pull requests, but ask contributors to keep in mind the following:
+
+* Only PRs with the template completed will be accepted
+* We will not accept PRs for user specific functionality
+
+### Developer Certificate of Origin
+
+In order for us to accept pull-requests, the contributor must sign-off a
+[Developer Certificate of Origin (DCO)](DCO1.1.txt). This clarifies the
+intellectual property license granted with any contribution. It is for your
+protection as a Contributor as well as the protection of IBM and its customers;
+it does not change your rights to use your own Contributions for any other purpose.
+
+Please read the agreement and acknowledge it by ticking the appropriate box in the PR
+ text, for example:
+
+- [x] Tick to sign-off your agreement to the Developer Certificate of Origin (DCO) 1.1
+
+## General information
+
+Python-Cloudant Client Library is written in Python.
+
+## Requirements
+
+- Python
+- pip
+
+It is recommended to use a [virtual environment](https://virtualenv.pypa.io/en/latest) during development. The
+python-cloudant dependencies can be installed via the `requirements.txt` file using pip.
+
+For example to create a virtualenv and install requirements:
+
+```sh
+virtualenv .
+./bin/activate
+pip install -r requirements.txt
+pip install -r test-requirements.txt
+```
+
+## Testing
+
+The tests need an Apache CouchDB or Cloudant service to run against.
+
+The tests create databases in your CouchDB instance, these are `db-<uuid4()>`.
+They also create and delete documents in the `_replicator` database.
+
+The tests are run with the `nosetests` runner. In this example the `ADMIN_PARTY` environment variable is used to tell
+ the tests not to use any authentication. See below for the full set of variables that can be used.
+
+```sh
+$ ADMIN_PARTY=true nosetests -w ./tests/unit
+```
+
+There are several environment variables which affect
+test behaviour:
+
+- `RUN_CLOUDANT_TESTS`: set this to run the tests that use Cloudant-specific features. If
+  you set this, you must set one of the following combinations of other variables:
+    - `DB_URL`, `DB_USER` and `DB_PASSWORD`.
+    - `CLOUDANT_ACCOUNT`, `DB_USER` and `DB_PASSWORD`.
+    - If you set both `DB_URL` and `CLOUDANT_ACCOUNT`, `DB_URL` is used as the
+      URL to make requests to and `CLOUDANT_ACCOUNT` is inserted into the `X-Cloudant-User`
+      header.
+- Without `RUN_CLOUDANT_TESTS`, the following environment variables have an effect:
+    - Set `DB_URL` to set the root URL of the CouchDB/Cloudant instance. It defaults
+      to `http://localhost:5984`.
+    - Set `ADMIN_PARTY` to `true` to not use any authentication details.
+    - Without `ADMIN_PARTY`, set `DB_USER` and `DB_PASSWORD` to use those
+      credentials to access the database.
+    - Without `ADMIN_PARTY` and `DB_USER`, the tests assume CouchDB is in
+      admin party mode, but create a user via `_config` to run tests as.
+      This user is deleted at the end of the test run, but beware it'll
+      break other applications using the CouchDB instance that rely on
+      admin party mode being in effect while the tests are running.
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
deleted file mode 100644
index b4b41f99..00000000
--- a/CONTRIBUTING.rst
+++ /dev/null
@@ -1,75 +0,0 @@
-Developing this library
-=======================
-
-Python-Cloudant Client Library is written in Python.
-
-===============================
-Developer Certificate of Origin
-===============================
-
-In order for us to accept pull-requests, the contributor must sign-off a
-`Developer Certificate of Origin (DCO) <DCO1.1.txt>`_. This clarifies the
-intellectual property license granted with any contribution. It is for your
-protection as a Contributor as well as the protection of IBM and its customers;
-it does not change your rights to use your own Contributions for any other
-purpose.
-
-Please read the agreement and acknowledge it by ticking the appropriate box in
-the PR text, for example:
-
-- [x] Tick to sign-off your agreement to the Developer Certificate of Origin (DCO) 1.1
-
-======================
-Development Quickstart
-======================
-
-Clone the repo into a folder, set up a `virtual environment <https://virtualenv.pypa.io/en/latest/>`_, 
-install the requirements:
-
-.. code-block:: bash
-
-    $ git clone git clone git@github.com:cloudant/python-cloudant.git
-    $ cd python-cloudant
-    $ virtualenv .
-    $ ./bin/activate
-    $ pip install -r requirements.txt
-    $ pip install -r test-requirements.txt
-    
-Before running the tests, start CouchDB:
-
-.. code-block:: bash
-    
-    $ couchdb
-
-The tests create databases in your CouchDB instance, these are `db-<uuid4()>`. 
-They also create and delete documents in the `_replicator` database.
-
-Now, run the tests. Here, I use the ``ADMIN_PARTY`` environment variable to
-tell the tests not to use any authentication. See below for the full set of
-variables that can be used.
-
-.. code-block:: bash
-
-    $ ADMIN_PARTY=true nosetests -w ./tests/unit
-    
-There are several environment variables which affect
-test behaviour:
-
-- ``RUN_CLOUDANT_TESTS``: set this to run the tests that use Cloudant-specific features. If
-  you set this, you must set one of the following combinations of other variables:
-    - ``DB_URL``, ``DB_USER`` and ``DB_PASSWORD``.
-    - ``CLOUDANT_ACCOUNT``, ``DB_USER`` and ``DB_PASSWORD``.
-    - If you set both ``DB_URL`` and ``CLOUDANT_ACCOUNT``, ``DB_URL`` is used as the
-      URL to make requests to and ``CLOUDANT_ACCOUNT`` is inserted into the ``X-Cloudant-User``
-      header.
-- Without ``RUN_CLOUDANT_TESTS``, the following environment variables have an effect:
-    - Set ``DB_URL`` to set the root URL of the CouchDB/Cloudant instance. It defaults
-      to ``http://localhost:5984``.
-    - Set ``ADMIN_PARTY`` to ``true`` to not use any authentication details.
-    - Without ``ADMIN_PARTY``, set ``DB_USER`` and ``DB_PASSWORD`` to use those
-      credentials to access the database.
-    - Without ``ADMIN_PARTY`` and ``DB_USER``, the tests assume CouchDB is in
-      admin party mode, but create a user via ``_config`` to run tests as.
-      This user is deleted at the end of the test run, but beware it'll 
-      break other applications using the CouchDB instance that rely on
-      admin party mode being in effect while the tests are running.