Restructure puppet-specifications reference for better flow

[DavidS]

Describe the Change You Would Like

The specs at https://github.com/puppetlabs/puppet-specifications/blob/master/language/resource-api/README.md have started to contain forward references and deep indentation. To improve legibility come up with a better structure to optimize for top-to-bottom reading. This is also a good opportunity to go through and crisp up a few words that have specific meanings and make sure they're defined once and then used consistently throughout.

This was originally filed as https://tickets.puppetlabs.com/browse/MODULES-9430