restructure the docs to move optional and hints out from the main section