add extensive documentation

Signed-off-by: Karl Isenberg <kisenberg@pivotallabs.com>