[docs] update example with a transition, add description to the docs