Suggested documentation fixes 

* Rather generate into a `docs` folder
* Upgraded to latest version of `asciidoctor`
* More documentation in `base`