This is very helpful. Let’s manually create documentation for a few (even one) resource(s) that we all agree is ideal. Then we can devise a strategy to apply that pattern more broadly in a manner that maximizes sustainability & usefulness.
At a minimum, I would expect every resource documentation to include information like:
- Brief overview/purpose of the resources with tips on usage and links to learn more.
- At least datatype, optional/required, default, and sample value for each property with links where appropriate (e.g., a datatype like “Patient UUID” would link to documentation on Patient.
- Possible responses
- Simple example (ideally, interactive against demo)
- A brief FAQ, if applicable, covering common mistakes, known limitations, etc.