Improve docs as per @jorisvandenbossche comments