edit docs: gs, contribute, minor other edits (#666)

* reorganize getting started

docs/source/contribute.rst

@@ -8,4 +8,16 @@ If you're interested in contributing to Cloud Custodian development, welcome! Pl
 Developer install
 -----------------
 
-First, you'll want to perform a :ref:`developer install <developer>` and familiarize yourself with the tests.
+You'll need to perform a :ref:`developer install <developer>` and familiarize yourself with the tests.
+
+Issues
+------
+
+We use `GitHub Issues <https://github.com/capitalone/cloud-custodian/issues>`_ to report and track work on the project.
+
+Discussion is also available on `Gitter <https://gitter.im/capitalone/cloud-custodian>`_ and a `Google Group <https://groups.google.com/forum/#!forum/cloud-custodian>`_.
+
+Contributor agreement
+---------------------
+
+Capital One requires that you accept and sign an agreement to license terms. See the `readme <https://github.com/capitalone/cloud-custodian>`_ for the agreement.

docs/source/developer.rst

@@ -3,7 +3,6 @@
 Developer Install and Testing
 =============================
 
-
 Requirements
 ------------
 

docs/source/filters.rst

@@ -1,5 +1,10 @@
 .. _filters:
 
+Filters
+=======
+
+These filters can be applied to all policies for all resources. See the :ref:`Resources and Actions reference <policy>` for resource-specific filters.
+
 Value Filters
 -------------
 

docs/source/quickstart/index.rst

@@ -3,15 +3,41 @@
 Getting Started
 ===============
 
-To install Cloud Custodian, just run:
-
-``pip install c7n``
-
-Then:
+See also the readme in the GitHub repository.
 
+* :ref:`install-cc`
+* :ref:`explore-cc`
 * :ref:`write-policy`
 * :ref:`run-policy`
-* :ref:`monitoring-env`
+* :ref:`monitor-cc`
+
+.. _install-cc:
+
+Install Cloud Custodian
+-----------------------
+
+To install Cloud Custodian, just run::
+
+  $ pip install c7n
+
+.. _explore-cc:
+
+Explore Cloud Custodian
+-----------------------
+
+* Run ``custodian -h`` to see a list of available commands.
+* Run ``custodian schema`` to see the complete list of AWS resources against which you can run policies. To invoke command-line help with more information about policy schema details, run ``custodian schema -h``.
+* Run ``custodian schema -<resource_name>`` to see the available filters and actions for each resource.
+* Drill down to get more information about available policy settings for each resource, where the model for the command is::
+
+  $ custodian schema <resource>.<category>.<item>
+
+  Examples::
+
+  $ custodian schema ebs.actions
+
+  $ custodian schema ecs.filters.instance-age
+
 
 .. _write-policy:
 
@@ -30,24 +56,75 @@ For more information, see the following topics:
 * :ref:`Example offhours policy <offhours>`
 * :ref:`Example tag compliance policy <tagCompliance>`
 
-TODO: content about ``custodian schema``? more detail about actually creating the policy, maybe more pointers to specific examples
+The ``custodian schema`` commands show you the available filters and actions for each resource. For each individual item, they also provide a detailed schema. For example::
+
+  $ custodian schema s3.filters.is-log-target
+
+provides the following information::
+
+  Help:
+  -----
+  
+  Filter and return buckets are log destinations.
+
+  Not suitable for use in lambda on large accounts, This is a api
+  heavy process to detect scan all possible log sources.
+  
+  Sources:
+    - elb (Access Log)
+    - s3 (Access Log)
+    - cfn (Template writes)
+    - cloudtrail
+
+  Schema:
+  -------
+  
+  {   'additionalProperties': False,
+      'properties': {   'type': {   'enum': ['is-log-target']},
+                      'value': {   'type': 'boolean'}},
+      'required': ['type'],
+      'type': 'object'}
+
+The policy is validated automatically when you run it, but you can also validate it separately::
+
+  $ custodian validate -c <policy>.yml
+
+You can also check which resources are identified by the policy, without running any actions on the resources::
+
+  $ custodian run --dryrun -c <policy>.yml -c <output-directory>
+
 
 .. _run-policy:
 
 Run the policy
 --------------
 
-TODO: command ...
+At its most basic, running a policy requires only the following command::
+
+  $ custodian run -c <policy_file> -s <output_directory>
+
+Custodian will create the output directory if it does not exist.
+
+This command writes the log files to the output directory. Note that the logs are appended to any existing log files; the logs are not overwritten by default. 
+
+.. _monitor-cc:
+
+Monitor resources
+-----------------
+
+Additional commands let you monitor your services in detail.
+
+You can generate metrics by specifying the boolean metrics flag::
 
-TODO: best practices for running with options specified in ``metrics and logs``.
+  $ custodian run -c <policyfile>.yml -s <output_directory> --metrics
 
-.. _monitoring-env:
+You can also upload Cloud Custodian logs to CloudWatch logs::
 
-Monitor your environment
-------------------------
+  $ custodian run -c <policyfile>.yml --log-group=/cloud-custodian/<dev-account>/<region>
 
-TODO: figure out whether the content from ``metrics and logs`` belongs here, rewrite?
-(still thinking about page organization -- more content for write, monitor, not so much for install, run)
+And you can output logs and resource records to S3::
 
+  $ custodian run -c <policyfile>.yml -s s3://<my-bucket><my-prefix>
 
+For details, see :ref:`usage`.
 

docs/source/quickstart/usage.rst

@@ -1,7 +1,7 @@
 .. _usage:
 
-Metrics and logs
-================
+Monitoring your environment
+===========================
 
 Cloud Custodian generates a consistent set of outputs for any given
 policy.
@@ -31,7 +31,7 @@ Additionally some filters and actions may generate their own metrics.
 In order to enable metrics output, the boolean metrics
 flag needs to be specified when running Cloud Custodian::
 
-  $ cloud-custodian run -c config.yml --metrics
+  $ custodian run -c <policyfile>.yml -s <output_directory> --metrics
 
 
 CloudWatch Logs
@@ -43,7 +43,7 @@ separate stream.
 
 Usage example::
 
-  $ cloud-custodian run -c config.yml --log-group=/cloud-custodian/dev-account/us-east-1
+  $ custodian run -c <policyfile>.yml --log-group=/cloud-custodian/<dev-account>/<region>
 
 
 If enabled, it is recommended to set a log subscription on the group to
@@ -61,6 +61,9 @@ with its log files for archival purposes.
 
 The S3 bucket and prefix can be specified via parameters::
 
-  $ cloud-custodian run -c config.yml --output-dir s3://my-bucket/my/prefix
+  $ custodian run -c <policyfile>.yml --output-dir s3://<my-bucket>/<my-prefix>
+
+Reports
+-------
 
 CSV reports can be generated with the ``report`` subcommand.