few cleanups (mainly docu) for upcoming release

@danielru Could you please review the little docu on the scalar example and possibly extend it a little bit? (either in the README.md or insource)