updated documentation with new by()-work.