updated documentation

the pr is prerry much messed up due to indentation. It may be easier to review the result without changes