Copied design goals to docs and some minor restructuring.

docs/getting_started.rst

@@ -77,8 +77,9 @@ get a base Ubuntu image ``ami-d85e75b0`` and launch an instance.
     inst = provider.compute.instances.create(
         name='CloudBridge-intro', image=img, instance_type=inst_type,
         key_pair=kp, security_groups=[sg])
-    # Refresh the state
-    inst.refresh()
+    # Wait until ready
+    inst.wait_till_ready()
+    # Show instance state
     inst.state
     # 'running'
     inst.public_ips

docs/topics/contributor_guide.rst

@@ -7,4 +7,7 @@ CloudBridge Provider.
 .. toctree::
    :maxdepth: 1
 
+    Design Goals <design_goals.rst>
+    Testing <testing.rst>
     Provider development walkthrough <provider_development.rst>
+    

docs/topics/design_goals.rst

@@ -0,0 +1,25 @@
+Design Goals
+~~~~~~~~~~~~
+
+1. Create a cloud abstraction layer which minimises or eliminates the need for
+   cloud specific special casing (i.e., Not require clients to write
+   ``if EC2 do x else if OPENSTACK do y``.)
+
+2. Have a suite of conformance tests which are comprehensive enough that goal
+   1 can be achieved. This would also mean that clients need not manually test
+   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
+   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
+   service with support for images and snapshots and various machine sizes.
+   The cloud infrastructure will very likely support block storage, although
+   this is currently optional. It may optionally support object storage.
+
+4. Make the CloudBridge layer as thin as possible without compromising goal 1.
+   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.

docs/topics/overview.rst

@@ -11,4 +11,4 @@ Introductions to all the key parts of CloudBridge you'll need to know:
     Object states and lifecycles <object_lifecycles.rst>
     Paging and iteration <paging_and_iteration.rst>
     Using block storage <block_storage.rst>
-    Testing <test.rst>
+

docs/topics/test.rst → docs/topics/testing.rst

@@ -1,7 +1,7 @@
 Running tests
 =============
-In the spirit of the set library `design goals`_, the aim is to have through
-tests for the entire library. This page explains the testing philosopy and
+In the spirit of the library's :doc:`design_goals`, the aim is to have thorough
+tests for the entire library. This page explains the testing philosophy and
 shows how to run the tests locally.
 
 Testing philosophy
@@ -61,8 +61,8 @@ You can toggle the use of mock providers by setting an environment variable:
 ``CB_USE_MOCK_PROVIDERS`` to ``Yes`` or ``No``.
 
 
-.. _design goals: https://github.com/galaxyproject/galaxy-cloudman-playbook/
-   blob/master/README.md
+.. _design goals: https://github.com/gvlproject/cloudbridge/
+   blob/master/README.rst
 .. _tox: https://tox.readthedocs.org/en/latest/
 .. _ProviderList: https://github.com/gvlproject/cloudbridge/blob/master/
    cloudbridge/cloud/factory.py#L15