Add design decisions docs page

Plus small typo updates

docs/conf.py

@@ -55,7 +55,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'cloudbridge'
-copyright = u'2015, GVL and Galaxy Projects'
+copyright = u'2017, GVL and Galaxy Projects'
 author = u'GVL and Galaxy Projects'
 
 # The version info for the project you're documenting, acts as replacement for

docs/topics/contributor_guide.rst

@@ -8,6 +8,7 @@ CloudBridge Provider.
    :maxdepth: 1
 
     Design Goals <design_goals.rst>
+    Design Decisions <design-decisions.rst>
     Testing <testing.rst>
     Provider Development Walkthrough <provider_development.rst>
     Release Process <release_process.rst>

docs/topics/design-decisions.rst

@@ -0,0 +1,20 @@
+Design decisions
+~~~~~~~~~~~~~~~~
+
+This document captures outcomes and, in some cases, the through process behind
+some of the design decisions that took place while architecting CloudBridge.
+It is intended as a reference.
+
+- **Require zone parameter when creating a default subnet.**
+
+  Placement zone is required because it is an explicit application decision,
+  even though ideally *default* would not require input. Before requiring it,
+  the implementations would create a subnet in each availability zone and return
+  the first one in the list. This could potentially return different values over
+  time. Another factor influencing the decision was the example of creating a
+  volume followed by creating an instance with presumably the two needing to be
+  in the same zone. By requiring the zone across the board, it is less likely to
+  lead to a miss match. (Related to 63_.)
+
+
+  .. _63: https://github.com/gvlproject/cloudbridge/issues/63

docs/topics/design_goals.rst

@@ -10,7 +10,7 @@ Design Goals
    against each provider to make sure their application is compatible.
 
 3. Opt for a minimum set of features that a cloud provider will support,
-   instead of  a lowest common denominator approach. This means that reasonably
+   instead of a lowest common denominator approach. This means that reasonably
    mature clouds like Amazon and OpenStack are used as the benchmark against
    which functionality & features are determined. Therefore, there is a
    definite expectation that the cloud infrastructure will support a compute
@@ -22,4 +22,4 @@ Design Goals
    By wrapping the cloud provider's native SDK and doing the minimal work
    necessary to adapt the interface, we can achieve greater development speed
    and reliability since the native provider SDK is most likely to have both
-   properties.
+   properties.