improve doc

some random improvements and additions i stumbled over while updating our project.
thanks for the hint @stof. better now?

tried to find a documentation or good yaml tutorial that i could link to as a reference about alias, but only found random blog posts that seem candidates for dead links rather sooner than later... but this should be good enough i hope.