Correct update task to match docs, add revision arg
Explain some doc conventions, per Bill's suggestion