diff --git a/README.md b/README.md
index eca23b7..f68c38c 100644
--- a/README.md
+++ b/README.md
@@ -1,19 +1,24 @@
 # SwiftShell
 
-A Swift module for shell scripting.
+An OS X Framework for command line scripting in Swift. It supports joining together shell commands and Swift functions, like the pipe in UNIX shell commands and the pipe forward operator in F#. As Swift itself it supports both object-oriented and functional programming.
 
 
-##  Usage
+## Usage
 
-Launch shell commands with `run("command")`. The output is a readable stream which you can `read()`, `readSome()` (read in parts, for large amounts of text) or split into `lines()`. For in-line commands you can use `$("command")`.
+Shell commands return readable streams, which can be read all at once with "read()" or read lazily (as in piece by piece) with "readSome()". The latter is useful for very long texts.
 
 ```
 #!/usr/bin/env swiftshell
 
 import SwiftShell
 
-let result = run("some shell command")
-print( "The time and date is " + $("date") )
+let result = run("some shell command").read()
+```
+
+For in-line commands, use `$("command")`.
+
+```
+print( "The time and date is " + $("date -u") )
 ```
 
 #### Pipe several commands together
@@ -39,7 +44,7 @@ for directory in directories {
 }
 ```
 
-or in a Functional Programming style:
+or more Functionally:
 
 ```swift
 environment["PATH"]! |> split(":") 
@@ -68,13 +73,13 @@ Launch with e.g. `ls | print_linenumbers.swift`
         cd SwiftShell
 
 - Copy/link `Div/swiftshell` to your bin folder or anywhere in your PATH.
-- To install the framework, either:
+- To install the framework itself, either:
   - run `xcodebuild install` from the project's root folder. This will install the SwiftShell framework in ~/Library/Frameworks.
   - _or_ run `xcodebuild` and copy the resulting framework from the build folder to your library folder of choice. If that is not "~/Library/Frameworks", "/Library/Frameworks" or a folder mentioned in the $DYLD_FRAMEWORK_PATH environment variable then you need to add your folder to $DYLD_FRAMEWORK_PATH.
 
-  - NOTE: if using Xcode 6.1 beta 2 (and possibly later), Release builds of SwiftShell will crash when using streams. Work around this by using debug builds instead:
+NOTE: Release builds of SwiftShell built with Xcode 6.1 beta 2 (and possibly later) crash when using streams. Work around this by using debug builds instead:
 
-            xcodebuild -configuration Debug install
+    xcodebuild -configuration Debug install
 
 
 ## LICENSE