GSoD 2020 - OpenMRS REST API Documentation

Hi @saurabh

First I would like you to create a survey. It will be great if you can come up with that during the community bonding period as @rainbow did. This will help us to identify what we are missing in the documentation which will be useful for developers and other users. It’s good if you can come up with set of questions which will help us to identify these issues.

I added a rough estimation for the time line in you’re doc that can vary during the project time. Let’s discuss about that later.

The survey is something we should focus during this period because last time also we didn’t get much feedback on the docs. Bu I think it is good if we can move forward with the feedback from the community it will help us to identify what we actually need to do.

2 Likes

sure @ayesh I will take @rainbow 's help in this and float a survey within the community bonding period and after that in the middle of the project as you indicated in the google docs. thank you for the suggestions on the timeline :slight_smile:

Yes that will be great. Actually lets not think about the time line for now. Lets see how the survey results going to be. Make sure to include a section in the survey to inform what are the tasks we are focusing on this project.And it will be good if the developers can give us an idea which order we should follow on achieving these tasks.

1 Like

yes @ayesh that would be great then we would be able to prioiritize our tasks and make a timeline accordingly.

exactly :smiley:

1 Like

@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