docs(README): Add usage instructions & other information to README

1 files changed, 37 insertions, 4 deletions

diff --git a/README.md b/README.md
index 539662686a80..0ed149fb8f0f 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-journalDriver
+journaldriver
 =============
 
 This is a small daemon used to forward logs from `journald` (systemd's
@@ -6,9 +6,42 @@ logging service) to [Stackdriver Logging][].
 
 Most existing log services are written in inefficient dynamic
 languages with error-prone "cover every use-case" configuration. This
-tool aims to fit a specific use-case and fit it very well, instead of
-covering every possible logging setup.
+tool aims to fit a specific use-case very well, instead of covering
+every possible logging setup.
 
-More documentation is forthcoming.
+In the initial version `journaldriver` will only work if deployed
+directly to a Google Compute Engine instance and will use the
+[metadata server][] to figure out credentials and instance
+identification.
+
+## Usage
+
+1. Install `journaldriver` on the instance from which you wish to
+   forward logs.
+
+2. Ensure that the instance has the appropriate permissions to write
+   to Stackdriver. Google continously changes how IAM is implemented
+   on GCP, so you will have to refer to [Google's documentation][].
+
+   By default instances have the required permissions if Stackdriver
+   Logging support is enabled in the project.
+
+3. Start Stackdriver, for example via `systemd`.
+
+## Upcoming features:
+
+* `journaldriver` will be added to [nixpkgs][] with a complementary
+  [NixOS][] module for easy configuration.
+* `journaldriver` will persist the latest `journald` cursor position,
+  allowing log reads to resume from the same position where they
+  stopped after a restart
+* `journaldriver` will attempt to figure out whether logs are in
+  JSON-format and use the coresponding `jsonPayload` field in
+  Stackdriver Logging to make structured logs easily accessible
+* `journaldriver` will support deployments on non-GCP machines
 
 [Stackdriver Logging]: https://cloud.google.com/logging/
+[metadata server]: https://cloud.google.com/compute/docs/storing-retrieving-metadata
+[Google's documentation]: https://cloud.google.com/logging/docs/access-control
+[nixpkgs]: https://github.com/NixOS/nixpkgs/
+[NixOS]: https://nixos.org/