GSOD 19 :- Developing User-Friendly Github Documentation for REST API final evaluation

Community Google Season of Docs
,
1

Hi All,

Primary Mentor: Burke Mamlin

Technical Writer: Ayeshmantha Perera.

Project Link: Developing User-Friendly Github Documentation for REST API

Documentation Link:- https://github.com/openmrs/openmrs-contrib-rest-api-docs

Documentation Server Link:- https://rest.openmrs.org/#openmrs-rest-api

Main Influence for the Project

What is OpenMRS & Where is it?

OpenMRS is a software platform and a reference application that enables the design of a customized medical records system with no programming knowledge (although medical and systems analysis knowledge is required). It is a common platform upon which medical informatics efforts in developing countries can be built. The system is based on a conceptual database structure that is not dependent on the actual types of medical information required to be collected or on particular data collection forms and so can be customized for different uses.

OpenMRS is now in use around the world (see the OpenMRS Atlas), including South Africa, Kenya, Rwanda, Lesotho, Zimbabwe, Mozambique, Uganda, Tanzania, Haiti, India, China, United States, Pakistan, the Philippines, and many other places. This work is supported in part by many organizations including international and government aid groups, NGOs, as well as for-profit and nonprofit corporations.

OpenMRS has a huge community and it is growing day by developers, technical writers, software testers and a lot of people using openMRS.The main influence is to provide them high-level documentation on API.

Main Objective.

The primary objective of the project is to develop interactive documentation where end-users can interact with APIs with try out options and in the meantime having a more descriptive and self-explained description that explains the technical and nontechnical people on what situation one should use the endpoint. The current swagger environment is great but for nontechies and techies still, it’s harder to get an idea directly without proper documentation. The main idea would be getting this swagger environment and documentation in one place with a nice representation. With the help of JS, HTML, and CSS.

Developing User-Friendly Github Documentation for REST API

Primary Goals

  • Write API documentation for resource types.
  • Integrate documents with Slate(Beautiful static documentation for your API ).

Contributions

  1. Write API documentation for resource types.

1*4YlYBp_66ERifILUh4pDIA.png1031×668

Pull Requests:-

2. Integrate documents with Slate (Beautiful static documentation for your API ).

Pull Requests:-

3. Write Overview documentation

Pull Requests:-

Future Works

During the program worked on main resource types still, there are few type to be covered. Currently, we only have the console-based example in the rest.openmrs.org which needs to be extended to have more examples with more programming languages.

Thoughts on GSoD

GSoD is one of the main programs in the world which encourages and helps people to engage in opensource development. The experience it brings to technical writers is very valuable for there future work.

As I always mention openMRS is one of the best opensource communities in the world. My mentor is always helpful for me when proceeding with the project. And motivated me to work towards the end of the project.

Finally, I would like to thank openMRS community who gave me this opportunity to work with the community and also to Google for organizing such an awesome opensource event for technical writers.

Final Presentation

@burke @dkayiwa @jwnasambu @gcliff @tendomart @jennifer Thanks alot all

3 Likes
2

Thanks alot @ayesh for the great work.

1 Like
3

thanks @ayesh,

Wonderful work

1 Like
4

@ayesh thanks for the great work. I humbly request you use this link to list the undone tasks as per your project. Once again thanks for choosing openmrs and hope to see more of your contribution.

1 Like
5

Great work @ayesh

1 Like
6

Well done @ayesh!

1 Like
7

thanks alot all

@jwnasambu sure will do

8

Thanks @ayesh for the great work

9

Hi all, taking some inspiration from @ayesh I also made my final project report and submitted it.

Develop user-friendly documentation for the OpenMRS rest API

Primary Mentor : Burke Mamlin .

Writer : Mohit Kumar .

Work product :

https://rest.openmrs.org/#openmrs-rest-api

Documentation source :

openmrs/openmrs-contrib-rest-api-docs [https://github.com/openmrs/openmrs-contrib-rest-api-docs]

About OpenMRS

OpenMRS is a software platform and a reference application that enables the design of a customized medical records system with no programming knowledge (although medical and systems analysis knowledge is required). It is a common platform upon which medical informatics efforts in developing countries can be built. The system is based on a conceptual database structure that is not dependent on the actual types of medical information required to be collected or on particular data collection forms and so can be customized for different uses.

OpenMRS is now in use around the world (see the OpenMRS Atlas), including South Africa, Kenya, Rwanda, Lesotho, Zimbabwe, Mozambique, Uganda, Tanzania, Haiti, India, China, United States, Pakistan, the Philippines, and many other places. This work is supported in part by many organizations including international and government aid groups, NGOs, as well as for-profit and nonprofit corporations.

OpenMRS has a huge community and it is growing day by developers, technical writers, software testers and a lot of people using OpenMRS software.The main influence is to provide them high-level documentation on API.

About the Project

The main objective of the project was to document a user-friendly REST API documentation which is interactive and easy to read and understand. The current REST API documentation which the OpenMRS community uses is the swagger documentation which is well documented, but it is only good for the existing developers and the people who are in the community for quite a while now. The new documentation is designed and documented in a way such that it easily understood by both new and existing developers, apart from developers any non-technical person can read and understand the API. The major improvements made in the documentation compared to existing one are :

  1. A real-life use-case of the API which is used, along with some conceptual definition which tells how a particular resource is used.
  2. Example request of the API.
  3. Easily understood by non-technical and technical people.

The goal of the project

  • The goal of the project was to document almost all of the resources used in the OpenMRS REST API.
  • Write the purpose of the documentation, a section that explains how to go through the documentation.

My Contributions

Resources :

  • Patient -> {Patient , PatientIdentifierType} -> {Merged, Merged}
  • Person -> {Person, PersonAttributeType} -> {Merged, Merged}
  • User -> {User, Role, Privilege} -> {Merged, Merged, In review}
  • Orders -> {Order, OrderType} -> {Merged, Merged}
  • Observations -> {Obs} -> {Merged}

Overview Documentation :

  • Purpose -> Add the purpose of the documentation as a general information for the documentation -> {In review}

Pull Requests :

Resources in documentation :

Overview of documentation :

Final Output

Future Scope

All the major resources are documented, but there is still room for a few more and in the console section of the slate documentation support for making the request in different programming languages can still be added.

GSoD 2019 : Daily Scrum Updates !

http://talk.openmrs.org [GSoD 2019 : Daily Scrum Updates !]

GSoD Overview

I personally found GSoD experience to be a very fruitful one, as the OpenMRS community provided me with all the support and help that I needed and I would like to thank my mentors and the community to give me this amazing opportunity.

Season of Docs is a very good initiative taken by google and with an experience like this, I would definitely love to participate in it next year.

4 Likes
10

Also this is the medium blog link for the same : https://medium.com/@kumar.mohit983/google-season-of-docs-at-openmrs-5662413eeab

11

Great work @batbrain7 . I kindly request you use this link to list the undone tasks as per your project. Once again thanks for choosing openmrs and hope to see more of your contribution.

12

Thank you so much @batbrain7 for this great work , you have made rest framework easy from the very basic to say

13

@batbrain7 thanks for the great contribution to the documentation.