Open
Description
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