(PDOC-35) Clarify types and providers example

- Clarify how desc/doc strings are automatically extracted
- Clarify in the example where my_parameter comes from
- add subheadings to Writing Compatible Documentation

README.md

@@ -119,6 +119,7 @@ future, here are some very basic examples to get you started using the strings
 module. These are very much subject to change as we continue to work out a
 style guide.
 
+### Functions
 Here's an example of how you might document a 4x function:
 
 ```
@@ -140,7 +141,9 @@ Here's an example of how you might document a 4x function:
      end
 ```
 
-And here's an example of how you might document a class:
+### Classes / Defined Types
+
+Here's an example of how you might document a class:
 
 ```
      # This class is meant to serve as an example of how one might
@@ -158,19 +161,21 @@ And here's an example of how you might document a class:
      ) { }
 ```
 
-Puppet providers often rely on different types of metaprogramming to create
+### Types and Providers
-parameters and methods. Since Strings does not execute the code which is being
-documented you must provide hints on how to document your code. To document a
-parameter which is automatically created you must use the special directive
-`@!puppet.provider.param` Which may take types, the parameter name, and a
-description.
-
 Strings will automatically extract the `@doc` provider docstring and any `desc`
-parameter docstrings.
+parameter/property docstrings.
+
+Sometimes however, Puppet providers use metaprogramming to create parameters
+and methods automatically. In those cases Strings will not be able to document
+them automatically (Strings doesn't execute the code that would generate those
+parameters), so you will need to provide hints on how to document your code. To
+document a parameter which is automatically created you must use the special
+directive `@!puppet.provider.param` which may take types, the parameter name,
+and a description.
 
 ```ruby
 # @!puppet.provider.param my_parameter This parameter needs to be explicitly
-# documented
+# documented as it is generated by mk_resource_methods
 Puppet::Type.newtype(:minifile) do
 
   @doc = "Manages files, including their content, ownership, and permissions.