have the docs make a wee bit more sense