GSoD 2020 - OpenMRS REST API Documentation

@saurabh & @ayesh, hopefully you’re seeing conversations like this one. I would recommend focusing on the human-readable content & examples (the content we don’t get from a tool like Swagger), assuming we will eventually want to combine this content with auto-generated information from our code (or even move this content into the code so full documentation can be auto-generated).

In other words, I would not spend a lot of time manually generating what can be automatically generated from code using tools like Swagger; rather, focus on the information a developer needs to effective understand & use the API. Ultimately, we’d like to be able to merge human written documentation and auto-generated documentation that is relatively easy to keep in synch with the code and goes beyond a simple enumeration of resources with little guidance on how/why/when to use them.

2 Likes

Hi @burke

Yes I think that will be great. Because code snippets we can actually generate from openAPI easily. What we need to focus is much on the how/why/when to use them.

Any starting point for moving forward would be great @burke. I really appreciate if we can have some inputs from you regarding what we can achieve from the project in this phase.

1 Like

@ayesh I think @burke is emphasising on the part that we should be focused more on code snippets and more descriptive content which we dont get from swagger.( something like we have in github documentation) like describing each param and resource in a human readable way with some usage context.

I would definitely add a suggestion block in the survey, I am currently working upon to get more views like these :slight_smile:

@saurabh @ayesh I would suggest the following approach which blends both needs

  1. Improve the speed of generation and quality of the generated docs - need to update from Swagger to OpenAPI?

  2. Embed example data and code snippets

  3. Look into generating the documentation and pushing it to a 3rd party hosting system - IMO even GitHub pages is good enough (can use a custom domain)

1 Like

@ssmusoke great suggestions,

but I think as far as the project description we dont want to go back to the dynamically generated docs rather we moved on from the swagger based documentation and we are planning to embed that swagger based documentation to the current static github documentation,

so that we could provide a try out feature to the people and the static documentation would serve as a source of concise and helpful examples and description about resources. ( examples in the static documentation might not be as exhaustive making use of all the parameters since our aim is to provide a good starting point to understand the endpoint and we can do any amout of experimentation in the swagger based try out feature, though the parameter description of each resource covers all those params exhaustively )

@saurabh Sorry I am late to the game, I am wondering why the automatically generated documentation is being discarded in favor of manually edited documentation, which I can guarantee will have a large gap even in the next 3 to 6 months

If you look at the issue I am facing, the manual documentation has lots of gaps, including a large mismatch already or maybe I am missing something

1 Like

@ssmusoke, the goal isn’t to discard the automatically generated inventory of resources, but to improve on it.

I would like to see decent documentation of key parts of the API (primarily key pieces: authentication, concepts, patient, visit, encounter, obs) that we all agree is top notch and that all devs (new & seasoned) find useful.

At this point the manual documentation and auto generated documentation both have faults/gaps. If you can help us get the manual documentation in excellent shape for these few key resources, then we can strategize how to expand that goodness to all resources and make it sustainable.

2 Likes

@ayesh I am almost done with the form could you please look up the form once and suggest some changes, after which I will post it in Talk for all the community members :slight_smile:

In the form, do you show an example of our best documented resource and ask them what they like and what they don’t like about it?

Do you ask them for an example (URL) of what they consider best of class REST API documentation?

1 Like

Sure great suggestions @burke added :slight_smile:

Yes I think both swagge and the rest doc seems to be having problems which we must try to fill as @burke mentioned.

Let’s go one by one @saurabh

Can you share the survey link here we can get @burkes and @ssmusokes suggetions before sharing it with the community :slightly_smiling_face:

1 Like

thanks @burke @ayesh @saurabh @ssmusoke for all the inputs on this!

1 Like

sure @ayesh the form can be accessed here

1 Like

Hi @burke @ssmusoke

@saurabh has shared the survey here.It will be really helpful for us to idnetify the missing parts if you have a look on it

Thank you

1 Like

@ayesh @burke @ssmusoke if the form looks good should I open the form for the community’s feedback, I will create a seperate post for it and link the post here .

1 Like

When I went for a last minute review of the form, I was greeted by a message saying “The form OpenMRS Rest API documentation Survey is no longer accepting responses. Try contacting the owner of the form if you think this is a mistake.”

@burke but I havent yet made the form open for accepting responses I thought I will do that after making it public on the talk

I made it open for accepting responses now !!

@saurabh, overall it looks good.

I’d consider making the first question optional. People may have useful feedback for you but not want to take the time to fill out a priority grid.

For me, the first question is hard to answer, because what I consider to be high priorities aren’t in the list. From my perspective, the approach would be something like:

  1. Documentation developers can count on for the basics & most commonly used parts of the API (e.g., authentication, patient, encounter/visit, obs) with helpful, concise documentation, good descriptions, and examples that work.
  2. Clean up issues with existing documentation (typos, broken links, “parroting” descriptions like foo’s bar property described as “Bar of the foo”, etc.), especially for resources in #1.
  3. Using output from #1 & #2 as our “north star” (exemplars of ideal documentation) to inform changes needed in source code so that we can auto-generate useful documentation for those resources.
  4. Updating source code annotations based on findings in #3, so we have decent auto-generated documentation.
  5. Creating/fixing a Maven task to generate Swagger documentation that can be woven together with static documentation to generate the content that we can host at rest.openmrs.org and could be built into the REST module to be served up in place of the current Swagger documentation.
  6. JS examples.
  7. Expand to more resources.
  8. Interactive examples.

In any case, don’t let perfect be the enemy of good… announce your survey in the dev category of Talk as soon as you have @ayesh’s approval. :slight_smile:

2 Likes

@burke thanks alot for the valuable feedback. I would agree on the priority of the list and it make sense to move forward on that way.

@saurabh I would suggest you to do the changes burke mentioned. Let’s publish it as soon as the changes are done.

Also great work on bringing up the survey so fast. Nice work @saurabh

1 Like