OpenMRS project

This page contains the details of a technical writing project accepted for Google Season of Docs.

Project summary

Open source organization:
OpenMRS
Technical writer:
Rainbow
Project name:
Improving OpenMRS Technical Documentations for New Developers
Project length:
Standard length (3 months)

Project description

Rationale

As the world is suffering the consequences of the COVID-19 pandemic, it is even more evident that an open source medical record system like OpenMRS can be a part of the solution for this kind of crisis. To help the new developers navigate the OpenMRS ecosystem, shorten their onboarding process, and allow more new comers to be able to quickly contribute to the development of OpenMRS, it is necessary to have concise, clear and up-to-date documentations. There are two existing documents for new developers: • Getting Started as a Developer • Developer Manual However, some of the contents are outdated and the format needs improvement. The goal of this project is to update the content and improve the format of these two documents to make them more user friendly.

Scope

  1. Re-organize and re-format the contents of these two documents. For the Getting Started as a Developer document: a. Divide the 17-steps in the instruction into sections, each section contains fewer steps, so that it is easier for the user to follow. b. Re-arrange the order of the steps; some steps can be combined. c. List links to other wiki pages in tables, so that the instructions are more concise and readable.

For the Developer Manual: a. The OpenMRS background information in the first few chapters can be shortened, the users can be directed to the OpenMRS.org page to find out more details. b. The Setting Up chapter should be moved up before the Development Process chapter

  1. Update the contents. For the Getting Started as a Developer document: a. Update environment set up for Linux and Windows (Introduce Docker) b. Update IDE configuration for IntelliJ and Eclipse c. Link to Developer Manual or Developer Guide wherever applicable. d. Make sure all the link-to contents are up-to-date.

    For the Developer Manual: a. Introduce the development workflow. b. Introduce how development teams are organized, how team members work together; add links to team meeting, team discussions; help new developers find the teams they might want to join. c. Add Docker in system setup chapter. d. Add more details about different kinds of modules (reference application module, OWA module and platform module), how they work together. e. Add simple example codes to show how each kind of modules are built and deployed. f. Add simple test examples for each kind of module.

Audience Analysis

The intended audience for the Getting Started as a Developer and the Developer Manual are developers that have little or no knowledge of OpenMRS. There could be two types of developers: The first type of audience is junior developers with little or no software development experience. For example, GSoC students, who are looking for real world projects to learn about open source software development. For these developers the two documents should present enough details and references so that they can begin to fill in the knowledge gaps, and start to contribute to the OpenMRS projects in a relatively short period of time. The major goals for junior developers are: 1. Understand the skills needed to participate in OpenMRS (MySQL, Java Spring. React.js, Git etc.) and find the resources to learn these skills. 2. Join the OpenMRS community, learn the communication tools. 3. Set up the environment and IDE. 4. Install OpenMRS SDK. 5. Understand the development workflow. 6. Produce simple code to create new modules. 7. Deploy newly created modules. 8. Test modules. 9. Use Git to make pull requests. The second type of audience is mid-level developers or senior developers looking to customize OpenMRS to suit their own organization’s needs or to contribute to OpenMRS. For these more experienced developers, the two documents should provide an overview of OpenMRS and serve as a guide to direct them to more in-depth technologies details in the Developer Guide and other resources. The major goals for experienced developers are: 1. Understand the data model and architecture of OpenMRS 2. Join the OpenMRS community, learn the communication tools. 3. Find links to OpenMRS code repositories. 4. Find more in-depth resources.

Project Plan

  1. Planning phase: • Refine the goals set in the Scope section • Identify outdated contents • Produce outlines for the two documents • Present the outline to the mentor and Subject Matter Experts (SMEs) • Update project plan

  2. Content development phase • Learn Docker, go through all installation steps, and produce simple example code/test code • Interview SMEs to ask questions • Develop the first draft of the two documents

  3. Content review and publishing • Self edit the contents • Send the completed drafts to reviewers (mentor and SMEs) and end users for feedback • Revise the draft • Publish the two documents in OpenMRS wiki page. • Write project report

Preliminary Work

I have done some work on development environment set up in Linux system and OpenMRS SDK set up. I am in the process of configuring IDE. I will continue to work on building simple modules and writing test code.

References and Discussions

https://talk.openmrs.org/t/breaking-down-walls-and-attracting-more-devs-to-openmrs/28502 https://talk.openmrs.org/t/openmrs-course-on-udemy-for-new-developer-learner/18861/14 https://talk.openmrs.org/t/looking-for-a-mentor-for-gsod2020-project-improving-documentation-for-new-developers/28999 https://talk.openmrs.org/t/a-possible-new-gsod-2020-project/28947