1. If working on 3.0, don't read 2.8 ?
Generally, we hope that if you're using ModeShape 3.x you only have to look at the documentation for 3. Lots of things have changed in 3.x vs 2.x, so we tried to migrate (rather than link to) most of the still-relevant parts of the 2.x documentation into the 3.x documentation (we might have missed a few things).
2. If say moving to version 4.0 (hypothetically) do you automagically move relevant information from 3.0 to 4.0 so that it's consistent and there are no gaps.
Yes, that would most likely be the goal.
I see more examples in 2.8 and I'm somewhat familiar the xml way (still learning bare bone jcr configuration). This is just one example, there's others.
Can you list more defficiencies that you found?