Give more detail about gosteno in the documents

Change-Id: Ib9393531fdfea069f4449063af016e46cf9bdb93

README.md

@@ -1,15 +1,49 @@
 # Gosteno
 
+Gosteno is a golang implementation of the
+[steno log tool](https://github.com/cloudfoundry/steno).  The feature set of
+Gosteno is very similar with that of ruby steno.
+
 ## Overview
 
-Gosteno is a golang implementation of the
-[steno log tool](https://github.com/cloudfoundry/steno).  The feature set of Gosteno is very similar with that of ruby steno.
+Core concepts behind Gosteno includes codec, sink, level, tag.
+
+### codec
+
+A codec encodes log entries to structural data, more specifically, JSON format
+data. Besides JSON codecs, Gosteno provides prettified codec which generates
+more human-readable data.
+
+### sink
+
+Roughly speaking, a sink is the destination where you store your log data. It's
+an abstraction of the underlying data storage systems. Currently Gosteno
+supports two kinds of sinks, namely IOSink and SyslogSink. IOSink includes files
+and standard output while SyslogSink streams your log data to syslog daemons
+such as rsyslogd. You can register as many sinks as you want. Everytime you log
+information, it will be written to all the sinks you have registered.
+
+### level
+
+Gosteno supports 9 levels(from low to high): all, debug2, debug1, debug, info,
+warn, error, fatal, off. You can change the level on the fly without respawning
+the process.
+
+### tag
+
+In gosteno, tags are extended information that will be encoded together with
+other normal log information. You can add as many tags as you want. Tag makes
+the log information extensive.
+
 ## Get Gosteno
 
     go get -u github.com/cloudfoundry/gosteno
 
 ## Getting started
 
+Here is a short but complete program showing how to registering sinks, chosing
+codec, tagging the information.
+
     package main
 
     import (
@@ -37,7 +71,9 @@ Gosteno is a golang implementation of the
 
 ## Change logger properties on the fly
 
-Changing logger properties such as log level without restarting system is allowed in Gosteno. It is achieved through a http interface by some APIs and data is exchanged as JSON:
+Changing logger properties such as log level without restarting system is
+allowed in Gosteno. It is achieved through a http interface by some APIs and
+data is exchanged as JSON:
 
   1. GET /regexp : get something like {"RexExp": "test$", "Level": "fatal"}
   2. PUT /regexp : put with data like {"RegExp": "test$", "Level":"fatal"}
@@ -55,6 +91,7 @@ Apache 2.0
 
 ## File a Bug
 
-To file a bug against Cloud Foundry Open Source and its components, sign up and use our
-bug tracking system: [http://cloudfoundry.atlassian.net](http://cloudfoundry.atlassian.net)
+To file a bug against Cloud Foundry Open Source and its components, sign up and
+use our bug tracking system:
+[http://cloudfoundry.atlassian.net](http://cloudfoundry.atlassian.net)
 

gosteno-prettify/README.md

@@ -0,0 +1,27 @@
+# gosteno-prettify
+
+gosteno-prettify is a command line tool which parses json formatted log lines
+from file(s), or stdin, and displays a more human friendly version of each line
+to stdout.
+
+## Setup
+
+    go get -u github.com/cloudfoundry/gosteno
+    cd $GOPATH/src/github.com/cloudfoundry/gosteno/gosteno-prettify
+    go install
+
+Don't forget to add the $GOPATH/bin to the $PATH
+
+## Usage
+
+    gosteno-prettify [OPTS] [FILE(s)]
+
+Examples :
+
+    gosteno-prettify f - g
+        Prettify f's contents, then standard input, then g's contents.
+
+    gosteno-prettify
+        Prettify contents of stdin.
+
+Fire `gosteno-prettify -h` to see more options.