diff --git a/README.md b/README.md
index 3b94eaaf..4b03b0ac 100644
--- a/README.md
+++ b/README.md
@@ -6,17 +6,72 @@
   
 # FlutterQuill  
   
-Rich text editor and a [Quill] component for [Flutter]. 
+FlutterQuill is a rich text editor and a [Quill] component for [Flutter]. 
   
-This library is a WYSIWYG editor built for the modern mobile platform only and web is under development. You can join [Slack Group] for discussion.
+This library is a WYSIWYG editor built for the modern mobile platform, with web compatibility under development. You can join our [Slack Group] for discussion.
 
 https://pub.dev/packages/flutter_quill
 
+## Usage 
+
+See the `example` directory for a minimal example of how to use FlutterQuill.  You typically just need to instantiate a controller:
+
+```
+QuillController _controller = QuillController.basic();
+```
+
+and then embed the toolbar and the editor, within your app.  For example:
+
+```dart
+Column(
+  children: [
+    QuillToolbar.basic(
+        controller: _controller, uploadFileCallback: _uploadImageCallBack),
+    Expanded(
+      child: Container(
+        child: QuillEditor.basic(
+          controller: _controller,
+          readOnly: false, // true for view only mode
+        ),
+      ),
+    )
+  ],
+)
+```
+
+## Input / Output
+
 This library uses [Quill] as an internal data format.
-Use `_controller.document.toDelta()` to extract it or use `_controller.document.toPlainText()` for plain text.
+
+* Use `_controller.document.toDelta()` to extract the deltas.
+* Use `_controller.document.toPlainText()` to extract plain text.
+
+FlutterQuill provides some JSON serialisation support, so that you can save and open documents.  To save a document as JSON, do something like the following:
+
+```
+var json = jsonEncode(_controller.document.toDelta().toJson());
+```
+
+You can then write this to storage.
+
+To open a FlutterQuill editor with an existing JSON representation that you've previously stored, you can do something like this:
+
+```
+var myJSON = jsonDecode(incomingJSONText);
+_controller = QuillController(
+          document: Document.fromJson(myJSON),
+          selection: TextSelection.collapsed(offset: 0));
+```
+
+## Configuration
+
+The `QuillToolbar` class lets you customise which formating options are available.  To prevent the image uploading widget from appearing, set `uploadFileCallback` to null.
+
+## Web
 
 Default branch `master` is on channel `master`. To use channel `stable`, switch to branch `stable`.
 Branch `master` on channel `master` supports web. To run the app on web do the following:
+
 1) Change flutter channel to master using `flutter channel master`, followed by `flutter upgrade`.
 2) Enable web using `flutter config --enable-web` and restart the IDE.
 3) Upon successful execution of step 1 and 2 you should see `Chrome` as one of the devices which you run `flutter devices`.