This page contains the details of a technical writing project accepted for Google Season of Docs.
Project summary
- Open source organization:
- OpenMRS.org
- Technical writer:
- batbrain7
- Project name:
- OpenMRS REST API documentation
- Project length:
- Standard length (3 months)
Project description
I will break down my proposal into different sections and will follow the flow like Google Maps API documentation and Github API documentation.
Apart from these I would also like to propose a readme structure for the API documentation that is done by realworld.io : https://github.com/gothinkster/realworld/tree/master/api
Personally, I found this documentation very easy to understand and use.
My proposal would mainly consist of 3 sections :
A section that would give a quick introduction about the API, about OpenMRS and about how the API is used and what all follows after that.
How to obtain the API key and the authentication that is needed in general to make the API request. This will consist a sample example of the types of authentication present in the API and keys and values that need to be present for it, also the types of values that are accepted corresponding to the key in that part. A code sample in any language would assist and clear out how to write the headers and response formats and other query parameters in the API.
The types of responses that are fetched by the API, the types of JSON or any other type of result that is returned by the APIs are to be mentioned.
The different API routes and what all parameters need to be sent along with those, the headers and other stuff. Each API will be assisted by code samples in a few languages that describe how the request is made while writing the code for it, apart from that general error codes that could be encountered with each API should also be mentioned.
This is a general idea of how the documentation will be defined for the REST API.
The schedule for the project is as follows :
1 August - 1 September
Get acquainted with my mentor and discuss in greater depth the level of documentation required at different parts of the codebase and also discuss how in depth to go in the low level vs high-level documentation. I’ll also spend this time understanding the codebase and study the concepts so that I can document them better.
Week 1 & 2
I will update and extend the contributors guide. I will improve the documentation on how to build the source code. I will also add a documenters section on how new contributors can help in documentation. I will study the different API documentation and start with the introduction and add the authentication for the API.
Week 3 - 8
I will add the API routes and responses along with some code samples for each type of API (there may be similar types of APIs).
Week 9 &10
Add the API documentation structuring using links, i.e a linked index for long API documentation and divide it further on a different basis such as code sections, overview, parameters, root endpoints.
Final Week
I will use the final week to prepare my final report of the work done during my 12 week documentation period. I’ll also spend this time to review and finalize the documentation.