GSoD 2019: Improved REST API Documentation

Tags: #<Tag:0x00007f7522230b10>

Hi @gcliff

Currently we didn’t had a call with @burke.But we have few paths identified.And am currently thought of working with https://rebilly.github.io/RebillyAPI/ redoc.

Had to get ideas about it from @burke

THANKS @ayesh for the feedback and am sure @burke will respond as soon as this comes to his notice

1 Like

Hi @burke

Will it possible to have a call to discuss about the projects

  1. As far as I understand and as gsod project page says I have to develop the github like documentation project.I would like to prefer ReDoc as the template to use it’s interactive by the nature as well.

I sent @burke so that we should wait for him and see schedule and find out when is the best time to meet him.

In the mean time are you folks*(@ayesh , @batbrain7) familiar with the currently available REST API Documentation Structure.

1 Like

Hey. Sorry for the delay in response. I am traveling over the next few days and attending a conference, so my schedule is difficult to predict.

My top priority for this project is concise, well-written text to help devs understand how to use the API. Using a tool like ReDoc is fine; however, I’d rather have a handful of well-written, concise, helpful descriptions of key API methods written by humans for humans than to see more “documentation” like this. To be clear, I do not consider a pretty interactive interface for a REST endpoint with a description like “Create an encounter.” as adequate documentation (in fact, I see it as a failure to document). If choosing between interactive documentation with auto-generated descriptions of methods like “Get a foo” or “Create a foo” vs. a paragraph or two explaining how to use a resource (e.g., that one of the GSoD students wrote after interviewing a few devs and testing the API with Postman or HTTPie) with a static example, I’d take the latter every time.

If I were to prioritize goals it would be something like this:

  • Concise, well-written descriptions of how/when to use a resource based on examining the code and interviewing devs.
  • The beginning of documentation similar to GitHub API documentation (not referring to the specific format/tooling; rather, the content & ease of reading/understanding)
  • Descriptions written in a simple format. While we could use the wiki, I’d personally prefer using simple Markdown, since it’s more portable.
  • A prioritized outline of what we’ll document. I’m less interested in a list of every known resource and more interested in what the first ~20 items we’ll focus on (e.g., introductory sections and then key resources). There’s some decent content here; though, it’s a bit dated.

Hopefully this can provide some context of what I’d like us to accomplish. Forgive me for not being able to schedule a call at the moment. We may be able to find a time for a call soon; however, in the meantime, let’s try to make due with asynchronous communication here.

2 Likes

Just sharing an example where our documentation needs improvement: Creat new REST endpoints in my module

cc @jwnasambu @c.antwi

1 Like

Hi @burke

I went through the API list as a start, as well as the content, provided REST Web Services API For Clients

Bit confused about where to get started how to separate the work between two of us. Shall I start on making something similar for GitHub API documentation web site?

Likewise @burke I am also a bit confused regarding the same.

cc @burke

…thanks

Hi @burke

I went through the current data model used in the openMRS in the mean time

https://docs.openmrs.org/datamodel/#

When will be possible to have a call and move forward :slightly_smiling_face:

@ayesh , @batbrain7 can you guys suggest the best times of your availability , we can arrange a call and update @burke ,it may be hard for him like he earlier indicated , and we have a deadline to meet. Tomorrow (17th , 18th and 19th are ok with me) 3-4 or 4-5pm EAT (1-2pm UTC)

@dkayiwa are you available at those times and dates so that you help out with curation i would like schedule a call on calender ?

Hi @tendomart

Yes 17,18,19 days are also ok for me.But can we make it little bit later (7pm,8pm EAT).Sounds good for me

Ayesh

Hi @tendomart

17, 18, 19 are also fine by me, but I’d also prefer the timings to be a bit late. like 8pm EAT.

Thanks

Alright we’ll wait for @dkayiwa @c.antwi @jennifer @gcliff @jwnasambu @irenyak1 to see if they can join us on call , we’ll have the final date later on today.

Please Do a DOODLE POLL

1 Like

I am in clinic tomorrow & have a conflict Wed, but could make it Thursday at 8p EAT (i.e., following the S&O call).

1 Like

Alright thanks @burke noted , we’ll then go with 19th 8pm EAT

2 Likes

@burke , @dkayiwa , @c.antwi , @gcliff

I was doing some experiment around the slate.And modified the template a little to suite openMRS are we finally trying to achieve something like this with more description and documentation ?

https://akayeshmantha.github.io/OpenMRS-docs/#welcome

1 Like

Thanks @ayesh for the update and good progress :+1:

Hello Team , hope all is well , just a reminder , we’ll have a call today at 8pm EAT , just after the operations call to help divide concerns between the two Tech Writers .

cc @burke @ayesh @batbrain7 @gcliff @jennifer @c.antwi

2 Likes