More work on project skeleton

CONTRIBUTING.md

@@ -1,6 +1,23 @@
 # Contributing to service-catalog
 
-Currently, we're collecting use-cases and requirements for a minimum viable
-product for the service catalog.  If you would like to propose or change a
-use-case, open a pull request to the project, adding or altering a file within
-the `docs` directory.
+This document should concisely express the project development status,
+methodology, and contribution process.  As the community makes progress, we
+should keep this document in sync with reality.
+
+## Development status
+
+We're currently collecting use-cases and requirements for our [v1 milestone](./docs/v1).
+
+## Methodology
+
+Each milestone will have a directory within the [`docs`](./docs) directory of
+this project.   We will keep a complete record of all supported use-cases and
+major designs for each milestone.
+
+## Contributing to a release
+
+If you would like to propose or change a use-case, open a pull request to the
+project, adding or altering a file within the `docs` directory.
+
+We'll update this space as we begin developing code with relevant dev
+information.

README.md

@@ -30,6 +30,7 @@ Broker.
 The service-catalog SIG will focus on a few key tasks:
 
 #### Service Catalog:
+
 1. Support a Service Catalog similar to what Cloud Foundry supports via
    their Cloud Controller APIs. This Service Catalog will support the
    notion of managing registered Service Brokers, which in turn dictates the
@@ -42,6 +43,7 @@ The service-catalog SIG will focus on a few key tasks:
    use the service instance provided to the application.
 
 #### Service Brokers
+
 1. Provide a framework to aide in the development of a Kubernetes-hosted 
    Service Broker that can then be registered into a Service Catalog - 
    either a Kubernetes Service Catalog or a Cloud Foundry one.
@@ -52,18 +54,19 @@ The service-catalog SIG will focus on a few key tasks:
    create a new set of DB tables per instance.
 
 #### Service Recipes
+
 1. Provide a Deployment Catalog that includes a list of pre-built deployable
    resources that can then be instantiated into a Kubernetes environment.
    Note that these may or may not be "Services" as defined above.
 2. These deployments, if they support the Service Broker APIs, can then be
    registered into the Service Broker for use by applications on the
    platform.
 
-This is the Kubernetes implementation of the service broker concept, which is
-joint effort amongst the different member organizations of the
-[CNCF](https://cncf.io/).
+The SIG will also monitor and discuss the progress made by the
+[Service Broker working group](https://github.com/servicebroker/servicebroker).
 
-Interested in contributing?  Check out the [documentation](./CONTRIBUTING.md)
+We are currently scoping our **v1** milestone [here](./docs/v1). Interested
+in contributing?  Check out the [documentation](./CONTRIBUTING.md)
 
 ### Use Cases
 
@@ -85,7 +88,7 @@ A very basic set of use cases to describe the problem space is:
 
 #### Advertising services and recipes
 
-Within and outside a Kubernetes cluster, there are services that users wish to
+Inside and outside a Kubernetes cluster, there are services that users wish to
 highlight and make available to other users.  Users might also wish to publish
 recipes that allow other users to run their own services.  Some examples:
 

docs/README.md

@@ -1,9 +1,9 @@
 ## service-catalog docs
 
-This directory contains documentation for versions of the service-catalog:
+This directory contains documentation for milestones of the service-catalog:
 
 1.  Use-cases
-2.  Architecture summary documents
+2.  Design documents
 
 Each version will get its own subdirectory.  Each version's documentation
 should be a complete accounting of supported use-cases, architecture, etc for

docs/v1/README.md

@@ -1,7 +1,10 @@
-## service-catalog v1 docs
+## service-catalog v1 milestone
 
-This directory contains design documents for the v1 version of `service-
-catalog`:
+This directory contains design documents for the v1 milestone.
 
 - [Use cases](./use-cases.md)
-- [Architecture](./architecture.md)
+- [Design](./design.md)
+
+## Status
+
+We are currently developing the use-cases and high-level design of this milestone.