There are a few ways to approach this…
a. Pick a few key resources
Take 2-3 resources that have high value & test different aspects of our documentation needs. For example:
- authentication - something everyone needs to be able to do
- obs – the key clinical data resource
- concept – an example of complicated metadata
b. Focus on a few resources people are asking about
Search Talk for examples of people struggling with the REST API like here, here, and here and focus on those resources.
c. Watch people try to use the REST API
Find a couple people who are familiar with OpenMRS and it’s data model, but who have never used the REST API, and record sessions of them trying to do some specific operations using the REST API (e.g., find a patient, register a patient, create a new concept for a fake lab test, record an encounter for the registered patient containing a result for the fake lab test).
With a & b, while you could requests the community to review & comment, but we’d want to enlist at least one n00b, one /dev/2, and one expert to review the documentation and make suggestions. It would probably be easiest for them to schedule a 30- or 60-minute call where they share their screen and read through the documentation and give you feedback. An alternative (or additional option) would be to convince/urge some developers who are doing active development to try using the documentation and then give you feedback on their experience.
With c, the person’s successes & challenges trying to learn & use the REST API would point out its strengths and weaknesses.