Improve documentation

Author: svenvc

README.md

@@ -1,13 +1,23 @@
 # NeoUniversalBinaryJSON
 An implementation of Universal Binary JSON (UBJSON) for Pharo.
 
-Universal Binary JSON (UBJSON) is a computer data interchange format. It is a binary form directly imitating JSON, but requiring fewer bytes of data. It aims to achieve the generality of JSON, combined with being easier and more efficient to process than JSON. The size/speed/efficiency differences are minor though, especially compared with compacted JSON. The implementation is simpler, though.
+Universal Binary JSON (UBJSON) is a computer data interchange format. It is a binary form directly imitating JSON, but requiring fewer bytes of data. It aims to achieve the generality of JSON, combined with being easier and more efficient to process than JSON.
+
+The size/speed/efficiency differences are minor for typical JSON payloads, especially compared with compacted JSON. The implementation is simpler, though, as there is no string escaping and no number parsing.
+
+UBJSON is making a larger difference when dealing with arrays containing numbers. Especially with ByteArrays, BJSON makes a huge difference, since these are essentially stored natively.
 
 See also
 
 - http://ubjson.org
 - https://en.wikipedia.org/wiki/UBJSON
 
+## Usage
+
+NeoUBJSONReader reads/parses a Universal Binary JSON stream. Use #on: to initialize it on a binary read stream and decode a value using #next. Its class side #fromByteArray: is convenient too.
+
+NeoUBJSONWriter writes/generates a Universal Binary JSON stream. Use #on: to initialize it on a binary write stream and encode a value using #nextPut:. Its class side #toByteArray: is convenient too.
+
 ## Installation
 
 This is a [Pharo Smalltalk](http://wwww.pharo.st) project