The Interviews Continue

by evoeges

This week, I conducted several more interviews with a range of people in OpenMRS. Experiences have ranged hugely from years to just a month. So far, most interviewees have been developers/contributors; but I have implementor/user interviews in the works. Some common themes have started emerging:

  • documentation as a part of development: a lot of people have spoken about the unfortunate ease with which documentation becomes outdated. There are a number of reasons for this, but the most obvious is that when a developer makes a change, fixes a bug, uploads a patch, etc. documentation isn’t an inherent step in their programming process. Some developers start a project and then abandon it, leaving half-finished pages that can be very confusing. Somehow, an environment needs to be created that emphasizes the importance of documenting every change that’s made. [There are certainly other reasons for lack of documentation: one person suggested it could be because the OpenMRS community is global, some community members may not be comfortable writing documentation in English.]
  • documentation needs ownership: people have suggested another major reason for out of date documentation; lack of central management. There’s no-one who is really leading the documentation project, and no dynamic personality or team to help (and encourage the community to) clean, remove, update and change documentation as needed. Several people have suggested a ‘documentation lead’; someone who can be the OpenMRS documentation caretaker and keep things fresh.
  • simplification: for many people, ‘documentation’ in the world of OpenMRS means so many different things that it can be difficult to locate and use information. There’s the wiki, floss manuals, mailing lists, IRC, etc. Many people find it difficult to understand what information goes where, and as a result, find it difficult to navigate through the various sources of documentation. Perhaps consolidation is in order? Or some an organizational system that can better help people navigate the world of documentation. This is important, not only for those seeking information, but for those who want to contribute to documentation as well.
  • space for beginners: many people spoke of the difficulty they experienced first getting started in OpenMRS. Though the community is extremely receptive and welcoming, actually loading up and testing out the software can be very difficulty. Many people gave specific suggestions to create a better space for beginners: both implementors and developers. An especially common theme was having more samples, examples, and hands-on activities.

I’ve been asking people as I go if they have any experience with exceptional documentation associated with other projects. So far, a great example has been the w3 schools documentation for learning HTML, CSS, JavaScript, etc.¬†The organization of the website is very logical and easy to follow, the table of contents is very explicit and detailed, navigation is simple, there are plenty of examples, and hands-on activities abound. It’s not exactly a perfect format for OpenMRS, but there are definitely some lessons that can be learned.

In the meantime, I made a rough sketch of the many roles fulfilled by the OpenMRS community, as it can be a little confusing at first glance.

OpenMRS Community Chart