Case Study: Sustainable OpenMRS Getting Started Guides

Owned by Jennifer Antilla
Dec 20, 2022
8 min read

Google Season of Docs 2021

Organization or Project: OpenMRS

Organization Description: OpenMRS (Medical Record System) is a robust, scalable, user-driven, open-source electronic medical record system platform currently used to manage more than 13.5 million patients at over 6,500 health facilities in 40 countries. Since 2004, OpenMRS has brought together a global community of committed individuals with medical informatics, IT, and global health expertise who are dedicated to improving patient outcomes by creating and maintaining the OpenMRS platform and modules. 

Authors: Jennifer Antilla, Brett Studer

Problem Statement

Many newcomers to the OpenMRS community go through a painful onboarding experience, particularly those who do not have a software development background, and remain at our entry-level OpenMRS Developer Stage. Two challenges prevent us from effectively linking these newcomers to projects that correspond to their skills and interest - and converting them into regular, long-term contributors: 

  1. Limited guiding documentation to onboard newcomers to new community projects.

  2. Limited technical writing capacity to create new and maintain existing Getting Started Guides for onboarding purposes.

As a result, we see too many newcomers leave the community before they even begin to make meaningful contributions. 

Proposal Abstract

By making strong Getting Started Guides for key community projects available, our community can provide a more engaging onboarding process for newcomers. Making a documentation toolkit for writing smart Getting Started Guides will help community technical writers create and update Getting Started Guides, now and in the future. 

Project Description

Creating the proposal

How did you come up with your Season of Docs proposal? What process did your organization use to decide on an idea? How did you solicit and incorporate feedback?

Our Documentation Team Lead heard about Google Season of Docs 2021 and shared the news at a community Documentation Team meeting as well as via our discussion forum (Talk). The Documentation Team asked the community to brainstorm ideas and then discussed suggestions during the team’s weekly call. Once we had a good set of ideas identified, we asked the community to vote on the project they wanted us to focus on for the proposal. 

We shared the proposal writing process with the community via Talk, including a link to the draft proposal itself so that everyone could contribute, review, and improve our proposal. The Documentation Team and our community’s Strategy & Operations Team contributed to developing and submitting the proposal and budget.

Budget

With our OpenMRS Fellowship Program, we established stipend levels for different stages of experience (Stage 2, Stage 3, Stage 4). We knew that we wanted an experienced technical writer (Stage 3 or higher) who would be able to work with community members who wanted to improve their technical writing skills. We used these stipend levels to inform our budget. Because we were prioritizing technical writing skills over community experience, we also budgeted in time for the community management and support needed to orient and bring our technical writer up to speed. We ended up needing more community management and support when the project expanded to include the Guide for the New & Curious and project pages.

We did not expect that some of our current fellows would become our technical writing fellows. This meant that we were able to share the cost of their stipend with their main fellowship project. In retrospect, we over budgeted in some areas, under budgeted in others, with the overall result being that we ended up slightly under budget.

Participants

This project was a collaboration between several OpenMRS Community squads and teams:

Documentation Team

@jennifer (OpenMRS Director of Community)

@gracebish (Documentation Team Coordinator)

@kaylinbracey(Documentation Team contributor)

@eddjomo (Documentation Team contributor)

@bstuder99 (Technical Writer)

Dictionary Manager Squad
@hadijah (Dictionary Manager Squad Dev/Technical Writing Fellow)

Quality Assurance Support Team
@christine (QA Support Team Lead)
@kdaud (QA/Technical Writing Fellow)

We found @bstuder99 through the Write the Docs Slack channel. His technical writing experience with user manuals and the fact that he was thinking about objectives of guides and materials from a user’s perspective corresponded with our primary needs. After making sure that our Documentation Team calls worked with his schedule, @bstuder99 joined our weekly Documentation Team call and helped our #docs Slack channel become more active. @jennifer oriented him to the OpenMRS community, answered questions, identified potential contacts within squads, and provided overall guidance and support. We had previously identified squads who might be interested in working with the Documentation Team on getting started guides through our Talk poll about GSoD projects. From there, we identified the best contacts to serve as content experts who might work with @bstuder99 and technical writing fellows. @kaylinbracey and @eddjomo volunteered to improve the Documentation Team’s own project page/getting started guide. @jennifer regularly attends the QA Support Team and FHIR Squad meetings, so she discussed the project with these two groups at their weekly meeting. She also put @bstuder99 into contact with @grace, OpenMRS’ Director of Product, about the Frontend Squad and Dictionary Manager Squad. When reaching out to the QA Support Team and Dictionary Manager Squads, we discovered that the identified content experts were keen to take up the technical writing tasks. The FHIR Squad did not have a content expert available to work with us initially, though this became a higher priority in October as interest increased. The Frontend Squad had made significant progress on their Getting Started as a 3.0 Developer guide; instead, streamlining their project page became our focus for this project and led to informed improvements to the community’s current Project Page template. 

Timeline

Give a short overview of the timeline of your project (indicate estimated end date or intermediate milestones if project is ongoing).

The onboarding process for the technical writer started in late May. The first phase of the project involved redesigning the introductory guides for onboarding all new contributors.

In the later phase of the summer (July and August), the focus shifted to creating a universal project page template that subgroups (squads/teams) within the community can use as a template for information for their projects. We modified several existing project pages utilizing this template as a means of displaying the utility, while also helping update those groups’ information flow.

The final phase of the project, taking place from late September to November, focused on the creation of Getting Started guides for different OpenMRS squads/teams. The work on this project changed from the creation creating new instructional guides for onboarding smaller specialized sects of contributors, to redefining existing tutorials based on user roles and organizing them within corresponding folders. Roles are usually designated by technical and non-technical users.

‘Results

What was created, updated, or otherwise changed? Include links to published documentation if available. Were there any deliverables in the proposal that did not get created? List those as well.

Significant and commonly-accessed documentation for OpenMRS has been updated to emphasize a greater instructional design, that gives new users the direct steps they need to perform to get acclimated to the projects they will be contributing to. These include:
Guide for the New & Curious, containing links to key team and squad project pages

Since our project expanded to include a series of linked tools to support onboarding for new community members, our “Getting Started Guide Toolkit” transformed into more of a “Documentation Playground,” with a README integrated into templates and examples of project pages & guides available.

Metrics

We initially proposed three metrics:

  • Up to 4 “How to Create a Getting Started Guide” recorded working sessions available in our Knowledge Center (# of recorded sessions available on Wiki)

  • “Getting Started Guide” Documentation Toolkit published to the OpenMRS Wiki (Y/N)

  • At least one Getting Started Guide per Technical Writer I is published to the OpenMRS Wiki (# of guides published/# of Technical Writing Fellows)

All of our working sessions occurred during our routine Documentation Team meetings. Each call was recorded, with the sessions held in July and August focusing most on supporting Technical Writers from the Dictionary Manager Squad (one technical writer) and QA Support Team (two technical writers) as they updated their project pages and improved their getting started guides. Our Documentation Team began updating its own project page and will then create a getting started guide for new technical writers. These recordings will be published on our Wiki as a part of the Documentation Team’s Getting Started Guide. 

We are already seeing multiple new community members being directed to our Guide for the New & Curious and at least two have gone on to introduce themselves to a specific squad, suggesting that our new guides and project pages are working. We expect the real test to come in the beginning of 2022, when we usually welcome a higher volume of new contributors interested in participating in Google Summer of Code.

Analysis

What went well?

Integrating our “Getting Started Guides” into a new member path is a huge win for our community. When potential new members land on our website’s “Get Involved” page, they are then taken to our updated “Guide for the New & Curious,” which includes links to the different squads’ and teams’ main project pages. These project pages then take them to the right “Getting Started Guide” for a particular project so they can begin contributing effectively. 

What was unexpected? What hurdles or setbacks did you face? 

We did not expect our technical writing fellows to come from the squads and teams seeking to improve their onboarding documentation. This turned out to be more effective than recruiting new technical writing fellows because it empowered the squads to be responsible for their own onboarding documentation. These squad members also had the advantage of being familiar with the project as a whole. 

Some squads were still debating whether to have their getting started documentation on github or on the wiki, which challenged our original idea of having a “Getting Started Guide” template for our Wiki.

Additionally, within the Documentation Team, stricter deadlines could have quickened the rate of deliverables. That being said, the main goals of the project were largely still accomplished within the predicted time frame.

Do you consider your project successful? Why or why not?

Overall, this project exceeded our expectations. Instead of improving documentation for the “getting started” stage of the new community member journey, we now have stronger documentation at four critical points in the new community member journey. These resources will serve as examples for other squads who chose not to participate in this Season of Docs.

Moreover, this project did not rely solely on a single technical writer to complete all of the materials. Existing fellows used this opportunity to improve their technical writing skills through this project and by liaising with our technical writer. In addition to building technical writing capacity within participating squads, this showed the broader community how the Documentation team can provide technical writing support to squads - instead of doing it for the squads.  

Summary

Through this year’s Season of Docs, we now have documentation to support our vision for onboarding OpenMRS Flight Paths. We have no regrets about the expanded scope of our project. 

@bstuder99’s flexibility and focus on the purpose of each onboarding document/step meant that our squads and teams were able to focus on valuable improvements to their project page and getting started guides. Even though @bstuder99 had not worked with our community before, he was able to look at our documentation for the new community member “flight paths” with fresh eyes and ask exactly the right questions. 

Sometimes, changes to a project’s scope work out for the better. Had we maintained our focus on a Getting Started Guides toolkit, we would likely continue to rely on our community members to personally guide new community members through the process of getting to know our community to finding potential squads/teams to work with to (finally) getting started with the squad/team.