diff --git a/README b/README
index bf99296..57da6a1 100644
--- a/README
+++ b/README
@@ -5,7 +5,7 @@ JSMN
 jsmn (pronounced like 'jasmine') is a minimalistic JSON parser in C.  It can be
 easily integrated into resource-limited or embedded projects.
 
-You can find more information on JSON at (http://www.json.org/)
+You can find more information about JSON format at (http://www.json.org/)
 
 Philosophy
 ----------
@@ -13,22 +13,25 @@ Philosophy
 Most JSON parsers offer you a bunch of functions to load JSON data, parse it
 and extract any value by its name. jsmn proves that checking the correctness of
 every JSON packet or allocating temporary objects to store parsed JSON fields
-is an overkill. 
+often is an overkill. 
 
 JSON format itself is extremely simple, so why should we complicate it?
 
 jsmn is designed to be	**robust** (it should work fine even with erroneous
-data), **fast** (it should parse data on the fly), **portable** (no unneeded
+data), **fast** (it should parse data on the fly), **portable** (no superfluous
 dependencies or non-standard C extensions). An of course, **simplicity** is a
-key feature - simple code style, simple algorithm, simple integration.
+key feature - simple code style, simple algorithm, simple integration into
+other projects.
 
 Features
 --------
 
 * compatible with C89
 * no dependencies (even libc!)
+* highly portable (tested on x86/amd64, ARM, AVR)
 * about 200 lines of code
 * extremely small code footprint
+* API contains only 2 functions
 * no dynamic memory allocation
 * incremental single-pass parsing
 * library code is covered with unit-tests
@@ -36,16 +39,22 @@ Features
 Design
 ------
 
-The rudimentary jsmn object is a **token**.
+The rudimentary jsmn object is a **token**. Let's consider a JSON string:
 
-When parsing is done, token objects contain start and end positions of JSON
-token inside the JSON data block. You can just copy a corresponding range of
-bytes and get token value. 
+	'{ "name" : "Jack", "age" : 27 }'
 
-Another propetry of token is token type. It describes the type of the
-corresponding JSON object. 
+It holds the following tokens:
 
-jsmn supports the following token types:
+* Object: `{ "name" : "Jack", "age" : 27}` (the whole object)
+* Strings: `"name"`, `"Jack"`, `"age"` (keys and some values)
+* Number: `27`
+
+In jsmn, tokens do not hold any data, but point to token boundaries in JSON
+string instead. In the example above jsmn will create tokens like: Object
+[0..31], String [3..7], String [12..16], String [20..23], Number [27..29].
+
+Every jsmn token has a type, which indicates the type of corresponding JSON
+token. jsmn supports the following token types:
 
 * Object - a container of key-value pairs, e.g.:
 	`{ "foo":"bar", "x":0.3 }`
@@ -54,46 +63,58 @@ jsmn supports the following token types:
 * String - a quoted sequence of chars, e.g.: `"foo"`
 * Primitive - a number, a boolean (`true`, `false`) or `null`
 
-jsmn doesn't handle specific JSON data types. It just points to the token
-boundaries - you should parse single data fields by your own if you need this.
+Besides start/end positions, jsmn tokens for complex types (like arrays
+or objects) also contain a number of child items, so you can easily follow
+object hierarchy.
+
+This approach provides enough information for parsing any JSON data and makes
+it possible to use zero-copy techniques.
 
-Get sources
------------
+Install
+-------
 
-Clone the repository (you should have mercurial installed):
+To clone the repository you should have mercurial installed. Just run:
 
 	$ hg clone http://bitbucket.org/zserge/jsmn jsmn
 
-Repository layout it simple: jsmn.c and jsmn.h are library files; demo.c is an
-example of how to use jsmn (it is also used in unit testing); test.sh is a test
+Repository layout is simple: jsmn.c and jsmn.h are library files; demo.c is an
+example of how to use jsmn (it is also used in unit tests); test.sh is a test
 script. You will also find README, LICENSE and Makefile files inside.
 
+To build the library, run `make`. It is also recommended to run `make test`.
+Let me know, if some tests fail.
+
+If build was successful, you should get a `libjsmn.a` library.
+The header file you should include is called `"jsmn.h"`.
+
 API
 ---
 
-Token types are described by `jsontype_t`:
+Token types are described by `jsmntype_t`:
 
 	typedef enum {
-		JSON_OBJECT,
-		JSON_ARRAY,
-		JSON_STRING,
-		JSON_PRIMITIVE
-	} jsontype_t;
+		JSMN_OBJECT,
+		JSMN_ARRAY,
+		JSMN_STRING,
+		JSMN_PRIMITIVE
+	} jsmntype_t;
 
-**Note:** primitive tokens are not divided into numbers, booleans and null,
-because one can easily tell the type using the first character:
+**Note:** Unlike JSON data types, primitive tokens are not divided into
+numbers, booleans and null, because one can easily tell the type using the
+first character:
 
 * <code>'t', 'f'</code> - boolean 
 * <code>'n'</code> - null
 * <code>'-', '0'..'9'</code> - number
 
-Tokens are described with `jsontok_t`:
+Token is an object of `jsmntok_t` type:
 
 	typedef struct {
-		jsontype_t type;
-		int start;
-		int end;
-	} jsontok_t;
+		jsmntype_t type; // Token type
+		int start;       // Token start position
+		int end;         // Token end position
+		int size;        // Number of child (nested) tokens
+	} jsmntok_t;
 
 **Note:** string tokens point to the first character after
 the opening quote and the previous symbol before final quote. This was made 
@@ -103,23 +124,26 @@ All job is done by `jsmn_parser` object. You can initialize a new parser using:
 
 	struct jsmn_parser parser;
 	jsmntok_t tokens[10];
-	
-	jsmn_init_parser(&parser, js, &tokens, 10);
+
+	// js - pointer to JSON string
+	// tokens - an array of tokens available
+	// 10 - number of tokens available
+	jsmn_init_parser(&parser, js, tokens, 10);
 
 This will create a parser, that can parse up to 10 JSON tokens from `js` string.
 
 Later, you can use `jsmn_parse(&parser)` function to process JSON string with the parser.
-It something goes wrong, you will return an error. Error will be one of these:
+If something goes wrong, you will get an error. Error will be one of these:
 
-* `JSON_SUCCESS` - everything went fine. String was parsed
-* `JSON_ERROR_INVAL` - bad token, JSON string is corrupted
-* `JSON_ERROR_NOMEM` - not enough tokens, JSON string is too large
-* `JSON_ERROR_PART` - JSON string is too short, it doesn't contain the whole JSON data
+* `JSMN_SUCCESS` - everything went fine. String was parsed
+* `JSMN_ERROR_INVAL` - bad token, JSON string is corrupted
+* `JSMN_ERROR_NOMEM` - not enough tokens, JSON string is too large
+* `JSMN_ERROR_PART` - JSON string is too short, expecting more JSON data
 
-If you get `JSON_ERROR_NOMEM`, you can allocate more tokens and call `jsmn_parse` once more.
-If you read json data from the stream, you can call jsmn_parse and check if
-return value is `JSON_ERROR_PART` to see if you have reached the end of JSON
-data.
+If you get `JSON_ERROR_NOMEM`, you can re-allocate more tokens and call
+`jsmn_parse` once more.  If you read json data from the stream, you can
+periodically call `jsmn_parse` and check if return value is `JSON_ERROR_PART`.
+You will get this error until you reach the end of JSON data.
 
 Other info
 ----------