Docs improvements

Some docs improvements solving some issues.
maybe add the link here

> that we can \[explain later](link for explanation)