WIP: api documentation

Looking for feedback on the addition of options/desiredState comparison. I have not implemented this yet, but I want to make sure we're in agreement of the changes that need to happen before I move on.
"Whereas Unit entities represent the desired state of units known by fleet, UnitStates represent the current live states of units running in the cluster. As such, there can be a slight divergence between the two after the desired state is modified, as the .." oh god I don't even know words are hard