What I’ve learned about documentation on my Outreachy internship and why it matters



If you haven’t read my previous posts – Hi! I’m Virginia and I’m a documentation Intern for LibreHealth EHR. I got this internship through Outreachy, an amazing organization which provides 3-month paid internships to people from underrepresented minorities all around the world. You can read about how I got this amazing opportunity here, and the struggles I’ve faced though my adaptation period here.

Now that the adaptation period is pretty much over, I’ve been enjoying being more productive and having a lot of fun in the process. I am excited about what I’m doing right now and even more excited about the plans we have for the next few weeks.

One of the reasons I chose this project was that it is a documentation project. I felt that I didn’t have enough technical knowledge to contribute to a development project, and I felt excited about this one in particular for several reasons:

  1. It directly benefits people: good documentation can make a world of difference for a user
  2. It allows me to combine my passion for technology with my teaching background
  3. It also allows me to use my language skills, since one of my main goals is to make the docs multilingual

So this week’s post is for anyone thinking of applying for LibreHealth EHR next round, and also for anyone writing any kind of documentation.

What is LibreHealth EHR?

LibreHealth is a collaborative community for free & open source software organization where several different health information technology projects collaborate. LibreHealth EHR is one of those projects.

EHR stands for Electronic Health Record. An electronic health record is essentially a collection of information about patients that is digitally stored. This makes information easy to share between different healthcare facilities and organizations. The information includes medical history, allergies, medications, demographics, tests results, and vaccination information, among other things.

The LibreHealth EHR application is a “clinically-focused” EHR which aims to be easy to use and customizable for a variety of health care settings. It is designed to cater for two main groups of users: staff members, such as front office staff and doctors. Likewise, LibreHealth EHR has two main types of documentation for these two categories of users: User Guides, and Admin Docs.

Why is documentation important?

According to the Health Care Information and Systems Management Society, adoption rates of electronic health records are remarkably slow compared to adoption of similar technologies by other industries. The reasons they cited for this are initial costs and decreased productivity during the implementation stage, but they also mentioned the quality and usability of the software. This makes documentation especially important: since the EHR will be used by people who don’t have a background in technology, they need documentation to be clear and easy to follow. This is the most important thing to keep in mind while writing User Guides.

This means:

  • Clear instructions split into steps: only combine short steps into one bullet point. If you cannot cover the visual part of the explanation with one screenshot only, you need a separate step.
  • Helpful screenshots: Use highlights, circles, rectangles, or any highlighting technique you prefer, to draw the reader’s attention to the section of the screen where they will be performing tasks.
  • Good references: if you have a more detailed explanation of something somewhere else, direct your reader towards it instead of leaving them to the task of browsing the whole site.

Admin docs are pretty similar to User Guides in that the final user is someone who doesn’t have a background in IT. However they do have administrative permissions, which means they are in charge of certain tasks that other staff do not have to deal with. This usually has to do with permissions, changing configurations, adding or removing users (staff members who are allowed to use the app), and related tasks. So their use of the app is a bit more involved.

The style of the documentation is the same though, and should be the same for every documentation anyone ever writes: don’t assume any prior knowledge and always give reference to concepts you don’t know for a fact the reader is familiar with, be clear and concise, and offer helpful visual aid, which saves the user a lot of time.


Writing good documentation is not easy, but it is extremely important and should not be neglected. We must not assume that users will “figure it out”. It is a really good exercise in empathy and communication skills. My teaching background has certainly helped a lot. Translating also has its own set of challenges, but I will leave that for another post.

If this post got you excited about documentation, and you’d like to contribute to LibreHealth EHR, stop by the LibreHealth Forums, and consider applying for the next round of Outreachy!


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s