Write readme and other doc files

[roncewind]

There are several places where documentation needs to be inserted. readme, various doc.go and docs.go files, main, Examples in the test files, etc etc.