Improve documentation in readme

README.md

@@ -1,17 +1,17 @@
 # Fischer960
 
-A Fischer Random Chess / Chess960 library for JavaScript.
+A Fischer Random Chess / Chess960 library for JS.
 
-```js
-import { generate, encode, decode } from 'fischer960'
+It uses algorithms to produce results, no large lookup tables needed.
 
+```js
 // Generate a random starting position
 let sp = generate()
 
 // Get the ID of the starting position
 let id = encode(sp)
 
-// Or, derive a starting position directly from its ID
+// Derive a starting position directly from its ID
 let sp518 = decode(518)
 ```
 
@@ -27,50 +27,77 @@ With NPM:
 
 # Use
 
-The three main functions (`generate()`, `encode()` and `decode()`) use algorithms to produce a result. No large lookup tables are used.
+The library is available as CJS for Node, ESM for bundlers and UMD for legacy environments. A bundler (Webpack/Rollup/etc) is recommended for use in browsers.
 
-IDs are zero-indexed (0-959), the standard starting position is #518.
+In modern JS environments it's common practice to import/require only the functions that are to be used:
 
-Functions that take an `arrangement` argument accept either an array (eg. `['B', 'B', 'Q', 'N', 'N', 'R', 'K', 'R']`) or a string (eg. `'BBQNNRKR'`).
+```js
+// ES module environments (Webpack/Rollup/etc)
+import { generate, decode, toUnicode } from 'fischer960'
 
-The main functions that return a starting position's arrangement (`generate()` and `decode()`) always return this as an array.
+// CJS environments (Node)
+const { generate, decode, toUnicode } = require('fischer960')
+```
+
+A few things to be aware of:
+
+- IDs are zero-indexed (0-959, the standard starting position having ID 518)
+- `generate()` and `decode()` return the starting position as an array (use the `toString()` helper function to convert it to a string)
+- An `arrangement` argument accepts either an array (`['B', 'B', 'Q', 'N', 'N', 'R', 'K', 'R']`) or a string (`'BBQNNRKR'`) of pieces
+- There's no validation, all functions expect valid input and may or may not break horribly if passed invalid arrangements or IDs
 
 ## Main functions
 
+### `generate()`
+
+Generates a random starting position, returning its arrangement of pieces.
+
+```js
+generate() // -> eg. ['R', 'N', 'B', 'Q', 'K', 'B', 'N', 'R']
+```
+
+Example for how to get both the ID and arrangement of a random starting position:
+
+```js
+// Pick a starting position at random
+let sp = generate() // -> eg. ['R', 'N', 'B', 'Q', 'K', 'B', 'N', 'R']
+
+// Get the ID of that starting position
+let id = encode(sp) // -> eg. 518
+```
+
 ### `decode(id)`
 
 Given an ID, returns the starting position's arrangement of pieces.
 
-This is the most effective way to get both the ID and arrangement for a random starting position:
+```js
+decode(518) // -> eg. ['R', 'N', 'B', 'Q', 'K', 'B', 'N', 'R']
+```
+
+Example for how to get both the ID and arrangement of a random starting position:
 
 ```js
 // Pick an ID at random
-let id = Math.floor(Math.round() * 960) // -> 0-959
+let id = Math.floor(Math.random() * 960) // -> 0-959
 
 // Get the starting position for that ID
-decode(id) // -> eg. ['B', 'B', 'Q', 'N', 'N', 'R', 'K', 'R']
+let sp = decode(id) // -> eg. ['R', 'N', 'B', 'Q', 'K', 'B', 'N', 'R']
 ```
 
 ### `encode(arrangement)`
 
 Given an arrangement of pieces, returns the starting position's ID.
 
 ```js
-encode(['B', 'B', 'Q', 'N', 'N', 'R', 'K', 'R']) // -> 0
+encode(['R', 'N', 'B', 'Q', 'K', 'B', 'N', 'R']) // -> 518
 encode('RKRNNQBB') // -> 959
 ```
 
-### `generate()`
-
-Generates a random starting position as its arrangement of pieces.
-
-```js
-generate() // -> eg. ['B', 'B', 'Q', 'N', 'N', 'R', 'K', 'R']
-```
-
 ## Helper functions
 
-A set of helper functions for manipulating arrangements are also provided. Except for `toString()` and `toArray()`, these return the same type that was provided (ie. if you pass a string you get a string back, same for array).
+A set of helper functions for manipulating arrangements are also provided.
+
+Except for `toString()` and `toArray()`, these return the same type that was provided (ie. if you pass a string you get a string, if you pass an array you get an array). Except for `toLowerCase()` and `toUpperCase()`, these also return the same case that was provided.
 
 ### `toString(arrangement)`