improves the doc based on the problems I've just had