Improving docs about validation

With some questions from our user mailing list
what happens if I do not call `flush()`? why? It would be nice to explain it here