improve the documentation with lots of examples