Thank you @herbert24 i will look through them
Interesting. So, this seems to confirm my assumption that people like concise, descriptive documentation (like GitHub’s docs) and would like to see it more comprehensive (covering more resources and including modules that extend our REST API).
I’m still advocating this approach:
- Get 1-3 resources documented manually to the point where everyone agrees “we want more of THAT!”
- In parallel:
- Begin fixing & expanding documentation to match the “gold standard” in #1
- Decide on the best mechanism (for now… avoid getting stalled waiting for perfect) to generate that documentation. How much can we generate from code? How can we limit the amount of documentation needed outside of the code? How can we accommodate modules that extend our REST API?
While I think the ideal solution would be most of the static documentation (except some manually managed text for intro/overview/auth/contributing) generated automatically by a Swagger-like tool grepping our code (including modules) with gaps filled by well-written annotations/Javadocs in the code, I don’t think figuring out the technical solution is a good use of GSoD. We need decent descriptions, examples, etc. whether they are written manually into a GitHub repo or placed in the code… we can always copy & paste them elsewhere in the future if needed.
So I will be working on resources ie patient,encounter,visit and obs for making them better and in parallel, I would be fixing and patching other parts of the documentation with examples and additions. when we would be ready with these 4 resources we can have a small review of these resources and then move forward with expanding this standard to other resources as well.
@ayesh I would edit the flow if you have some changes to suggest !!
I would say yes but cross-check it with the swagger
Yes I like that approach.
So what are the first 3 resources we are going to document.
I believe it’s best to get developers input for the documentation. Will it work if we go with another survey to identify missing points. Or direct messages may be a new talk thread where all dev people can give their opinion would work ?
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
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.
should we add responses for all restAPI calls that we have or some specific ones ?
Shall we first finish Java Examples?. Adding examples in the current form is easy. But we have to focus on what @burke mentioned here.
@ayesh in the auth section when we are able to retreive a session token after authentication then how do we use it with subsequent requests to other endpoints,
as of now I am sending the basic auth header with each of my requests is it possible to do the other way around as well using the session token ?
Hi @saurabh, no, currently, only the basic auth is what in place. Anyway, few modules were coming up with the support of session tokens. For example, keycloack IDP based solutions that are coming up for enterprise-level openMRS integrations, which federates openMRS user base to keycloak and perform authentication and authorization based on oauth2 and OpenID connect. Which will give us a session token where we can perform authorization based on that token with the help of OIDC. But for now we don’t have to worry about it.
ok @ayesh I will just add one basic auth example in that section and leave the jsession token part for now !!
@ayesh I need some help in the last section of the auth resource in this PR could you look at my comments
hi @ayesh do you have some time to help me look through this task on the trello board https://trello.com/c/m6LOgm64/19-update-our-old-rest-wiki-pages-to-point-to-the-new-rest-documentation cc @burke
he has done it already @herbert24 for my current trello tasks !!
I merged youre pr.Now lets focus on what @burke mentioned.I saw u have created a draft pr for concept.Looks good.
Can we find few talk posts where developers or new comers found problematic to use the authentication in openmrs ? As a start point ?
Actually @ayesh I have made a list of those talk posts and I am going to remove all those issues in the 3 resources that burke pointed out.
I am done with authentication and currently working on concept section . also I am trying to encorporate all those changes which burke deemed as minimum requirement for each resource here
after I am happy with the current state of these three resouces then we can have a reveiw or a survey again of these theree resources while in parallel I will continue working on other resources and get back to these resources after getting feedback from people
Great man.Please share the links in the thread so we can get @burkes opinion as well.
Good work done so far keep it up
sure @ayesh I will be linking all my PRs here and in trello as I am doing