update documentation for onconfirm to other words

I find the first draft very difficult to understand. Maybe this (and the examples) help to clarify