In many places we have attributes that are almost verbatim constructed from the object returned by a given OpenStack API. These then allow deeper introspection via get_attr function, but the user has no clear indication on which OpenStack API to examine to find out what values can be extracted from such attribute.
Example: OS::Neutron::Pool has 'vip' attribute, that can be used to get the 'port_id' of that vip, although it is completely unclear for the user how/from where this 'port_id' appears as it is not present in the attribute schema presented by Heat.
We should at least document such attributes pointing user to what API schema of which OpenStack service (s)he should examine to find out possible values to use with get_attr on such attribute.