Reviewing snapcraft.yaml schema documentation

Ideally this should sync up with the reference but really they should both be automatically generated or partially generated by the continuous integration system in the Snapcraft repository.