Improve README

Improve existing instructions and wording.

Apply README template.

Change-Id: I9327345b70d682948dfe2e7f8e67c0f5b00cebbb

src/README.md

@@ -1,49 +1,64 @@
 # Overview
 
-Gnocchi is an open-source, multi-tenant timeseries, metrics and resources
-database. It provides an HTTP REST interface to create and manipulate the
-data. It is designed to store metrics at a very large scale while providing
-access to metrics and resources information and history.
+[Gnocchi][gnocchi-upstream] is an open-source, multi-tenant timeseries,
+metrics, and resources database. It provides an HTTP REST interface to create
+and manipulate the data. It is designed to store metrics at a very large scale
+while providing access to metrics and resources information and history.
 
 # Usage
 
+## Configuration
+
+See file `config.yaml` for the full list of configuration options, along with
+their descriptions and default values. See the [Juju
+documentation][juju-docs-config-apps] for details on configuring applications.
+
+## Deployment
+
 Gnocchi is typically deployed as part of an OpenStack cloud, providing storage
-for Ceilometer, the telemetry collection service; To deploy Gnocchi to an
-existing OpenStack cloud (which includes ceilometer):
+for Ceilometer, the telemetry collection service. To deploy Gnocchi to an
+existing OpenStack cloud (which already includes Ceilometer):
 
     juju deploy gnocchi
     juju deploy memcached
-    juju add-relation gnocchi mysql
-    juju add-relation gnocchi memcached
-    juju add-relation gnocchi keystone
-    juju add-relation gnocchi ceph-mon
-    juju add-relation gnocchi ceilometer
+    juju add-relation gnocchi:shared-db percona-cluster:shared-db
+    juju add-relation gnocchi:coordinator-memcached memcached:cache
+    juju add-relation gnocchi:identity-service keystone:identity-service
+    juju add-relation gnocchi:storage-ceph ceph-mon:client
+    juju add-relation gnocchi:metric-service ceilometer:metric-service
+
+The Gnocchi API should now be used to service information queries. As such,
+once re-configuration caused by the above relations has settled, the Ceilometer
+API will be disabled.
+
+Gnocchi then needs to be initialised with the current Ceilometer data:
 
-After re-configuration the Ceilometer API will be disabled - the Gnocchi REST
-API should be used to query information on resource, metrics and associated
-measures.
+    juju run-action --wait ceilometer/leader ceilometer-upgrade
 
-Gnocchi then needs to be initialized with the current ceilometer data:
+## S3 storage backend support
 
-    juju run-action <ceilometer unit leader> ceilometer-upgrade
+The gnocchi charm by default uses Ceph as a storage backend (the default value
+of option `storage-backend` is 'ceph') but it also has support for S3 storage.
 
-# Usage with S3 storage backend
+> **Note**: S3 storage support is available starting with OpenStack Stein.
 
-> **Note**: S3 storage support for Gnocchi is available starting with OpenStack
-  Stein.
+To configure Gnocchi to use S3 the following configuration options must be
+set accordingly:
 
-Gnocchi is configured to be deployed by default with Ceph, however,
-it can also connect to an S3 storage backend. To configure Gnocchi with S3,
-configuration options (`storage-backend`, `s3-region-name`, `s3-endpoint-url`,
-`s3-access-key-id` and `s3-secret-access-key`) must be provided.
-Please take a look at `config.yaml` for more details.
+* `storage-backend`
+* `s3-region-name`
+* `s3-endpoint-url`
+* `s3-access-key-id`
+* `s3-secret-access-key`
 
-## Policy Overrides
+See file `config.yaml` for more details on the above options.
 
-Policy overrides is an **advanced** feature that allows an operator to override
-the default policy of an OpenStack service. The policies that the service
-supports, the defaults it implements in its code, and the defaults that a charm
-may include should all be clearly understood before proceeding.
+## Policy overrides
+
+Policy overrides is an advanced feature that allows an operator to override the
+default policy of an OpenStack service. The policies that the service supports,
+the defaults it implements in its code, and the defaults that a charm may
+include should all be clearly understood before proceeding.
 
 > **Caution**: It is possible to break the system (for tenants and other
   services) if policies are incorrectly applied to the service.
@@ -61,7 +76,17 @@ Here are the essential commands (filenames are arbitrary):
 See appendix [Policy Overrides][cdg-appendix-n] in the [OpenStack Charms
 Deployment Guide][cdg] for a thorough treatment of this feature.
 
+# Bugs
+
+Please report bugs on [Launchpad][lp-bugs-charm-gnocchi].
+
+For general charm questions refer to the [OpenStack Charm Guide][cg].
+
 <!-- LINKS -->
 
+[cg]: https://docs.openstack.org/charm-guide
 [cdg]: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide
 [cdg-appendix-n]: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/latest/app-policy-overrides.html
+[juju-docs-config-apps]: https://juju.is/docs/configuring-applications
+[lp-bugs-charm-gnocchi]: https://bugs.launchpad.net/charm-gnocchi/+filebug
+[gnocchi-upstream]: https://wiki.openstack.org/wiki/Gnocchi