Rework the state documentation

Make the state documentation easier to understand, more
clear, and better stated than what existed before this
commit so it is easier for users to read, use and
interpret.

Change-Id: I0285bfe332c6e968626719f14049a9533d066d86
Merge "Rework the state documentation"