Feedback on documentation

[polytypic]

There is always room to improve documentation.

At least for me it can be very difficult to see where the documentation I've written, for code I've designed, isn't necessarily clear enough, because I know too much about the code already.

Feedback on anything that is hard to understand and could perhaps be improved is most welcome.