reworked initial doc from francois. not perfect yet, still have a few open questions