Add doc

Hi,

This is the last PR before tagging official release. Next to @manuakasam doc, I've added the part to outline the problem we had in the issue. @danizord and @arekkas could you quickly have a look?