Improve/complete/refactor documentation.

This is an attempt at improving the doc.
Comments welcome, no problem if not merged.