improve documentation with yaml example + fixes