I’m far less interested in another round of Swagger documentation tweaks producing variations on this, where pretty colors, rounded boxes, and interactive “documentation” get prioritized over descriptive content. What the OpenMRS community really needs is clean & concise, well-written documentation of our REST API that targets both introduction (for those new to the API) and reference (for those looking for details on a part of the API they haven’t used lately). We also need to keep things simple, since it’s important to produce something that can be maintained. There are several documentation generators around we could consider; just ask google or find lists like this… but I’d be fine to start with simple Markdown.
These are the types of things that I’m thinking about regarding REST API documentation:
Use Markdown
Prioritize concise, pragmatic, descriptive content (e.g., teach someone how to authenticate to the REST API in a few minutes, explain what’s working for orders and what isn’t).
Support syntax highlighting, since good examples are priceless
Avoid the shiny/attractive niche tool that might be abandoned in 1-2 years
Search, table of contents, support for translations of the API are nice-to-haves, but lower priority than having quality content.
We’ll want to create a backlog (prioritized list of things to document) and then divide & conquer.
Just a one thing to clarify.From the two projects descriptions of mine and @batbrain7 I kind of feels that we both are working on a joint project am I right.
Correct. We defined one project to improve our REST API documentation, both of you applied to work on that project, and both were accepted by GSoD. So, we’ll work as a team to divide & conquer. This can be very good news, since we have no shortage of REST API endpoints to document.
Yes that is an excellent decision..Awesome .I think it will be great to have a call and discuss about our next steps after we go through the materials that @burke mentioned am I right @batbrain7.
Sure will have a look on them.And I think it wil be good of we can have both mark down and try out options if am right as @burke mentioned in a previous thread.
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.
Will it possible to have a call to discuss about the projects
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.
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.
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?
.Awesome 
.I think it will be great to have a call and discuss about our next steps after we go through the materials that 