What's up Doc(umentation)?

OPW with OpenMRS Summer 2013- documentation style

Month: July, 2013

Phase 1 Draws to a Close

This week, my work bounced all over the place (in the best way possible). I’ve been finishing up the last of my interviews (I still have a few scheduled for next week). It’s great to see all of the information coming together into a very comprehensive overview of user/developer/implementer/contributer interaction with documentation.

This week, I’ve also been sorting through the existing pages of the OpenMRS wiki and roughly sorting them into three categories:

  • Extensive work needed: these are the pages that are very out of date, or have very little (if any information) and will need to be heavily worked on to bring up to speed. For these, the module will need to be downloaded and run, and the code will need to be looked at.
  • Some work needed: these are the pages that have fairly basic information already, though perhaps not organized and missing some components. These pages don’t need as much work, but maybe still some hands on module-use or a glance at the code to fully update.
  • Comprehensive: these pages are great examples of documentation, and have been pointed out by members of the community or follow the requirements they’ve discussed. The HTML form entry page is the best example. Perhaps some minor changes will be needed, but for the most part, these pages are spot-on.

Of course, these divisions are fairly rough and some changes will be made, but for now it’s useful to wrap my head around the documentation that’s out there and the work that needs to be done.

I’ve also been brainstorming the best ways to show of the information I’ve been collecting. I’ve read through a collection of design and graphic design e-books from my school library. I’ve been focusing in on infographics as a useful way to coalesce, synthesize and disseminate what I’ve learned. A simple infographic can go a long way in concisely but precisely showing what’s important about documentation. It can be given to any newcomers who are interested in documentation, as well as existing community members. It’s obviously not the finale of what I’ve been working on, but it is a useful tool that’s a natural byproduct of my work to this point. To this end, I’ve also been familiarizing myself with different types of infographics, and the thought processes behind them; what information? why this information? how should it be displayed? what is the intent? Online tutorials for planning and specific programs (including inkscape) have been on my plate for the week.

To that end, I’ll be putting up a few of my rough drafts in the coming days, as soon as they become blog-worthy.


Module Models

This week I’ve been specifically focusing on modules. Modules in OpenMRS are an integral aspect of the software. They are the customize-able ‘add-ons’ that make OpenMRS so well-suited for so many different users. Module documentation has a lot of problems though, as many of the people I’ve interviewed have pointed out. There’s no really clear formula for writing documentation, so two wiki pages on two different modules might be completely different, and as a result, miss on out on important information. Many modules simply aren’t documented, or have such minimal documentation that they’re still exceptionally difficult to parse through. Documentation is vital for functioning modules: not only for downloading and setting up the modules, but for troubleshooting. Modules aren’t just bonus add-ons to OpenMRS; in many situations, modules are integral components in having a useable software.

From the feedback I’ve gotten on module documentation, here are the core ideas:

  • accountability: if developers themselves don’t have the time to write documentation on their modules, there needs to be a way to pass responsibility to someone to ensure that the documentation at the very least, exists. This person or people should also be responsible for making sure module documentation stays up-to-date. For example, if someone is discussing a problem with a module or a unique usage of a module on a mailing list, adding that to the module’s wiki page could be enormously helpful for future developers/users/implementors. Rather than digging through old mailing list logs, all of the information pertaining to the module is displayed on the module’s wiki page. One interesting solution would be to keep an updated list of all the module documentation that needs to be written or updated. Anyone new to OpenMRS wishing to make a contribution could access this list. It would be a great way for them to learn about OpenMRS and how it works, and keep documentation updated for the rest of the community.
  • beginner/advanced division: one way to keep documentation accessible for OpenMRS newcomers, but also relevant for more advanced developers would be to divide module documentation into beginner and advanced sections. A beginner section might be a conceptual explanation of the module, with some technicality . A more advanced explanation would go into more technical detail (for example, what are the important classes or functions in the code? how do they interact with one another and code from other modules) and include examples of code. A lot of people said that they themselves, or someone they knew, were scared away from OpenMRS at first because of the complexity of much of the documentation. Making information more accessible to newcomers is important to welcome and facilitate their understanding.
  • organization: I’ve spoken of it before, but it’s a testament to the importance of clear and logical organization that it keeps coming up in my interviews. One simple way to provide good organization is by adding a table of contents to the beginning of every module page. At a glance, a person can (hopefully) see exactly where the information they’re searching for might be located. Another aspect of organization that I’ve spoken of is consolidation; keeping information more or less in one place. This ties in to the first point of trying to place vital information from the mailing list on the wiki as well.
  • visuals: this is a very simple way to add clarity and information to a module page, and many people have attested that visuals are an excellent way to enhance documentation. There’s a range of possibilities for this, from a flow chart that demonstrates what functions call one another to screenshots of the module at work or during the installation phase.

Here’s an outline of what a module documentation framework could be:

Untitled drawing (1)


The Interviews Continue

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

Community (Inter)Views

In the coming week or so, I’ll be conducting interviews with as many people involved in OpenMRS as possible; developers, contributers, implementors, users. The biggest part of the documentation challenge is building something that the community wants to use and contribute to.  Michael and Burke helped develop a set of basic questions as the groundwork for the interviews, and hopefully as stepping-off points for taking advantage of the community as a resource for design:

  •  How do you interact with OpenMRS — Are you a developer or contributor? Are you an implementer? A user?
  • When you want to find an answer to something OpenMRS, what do you typically do?
  • What tools or methods do you generally start with? If that doesn’t work, what do you try next? What happens when you can’t find the answer?
  • What do you like about the currently available OpenMRS documentation?
  • What do you think could be most improved about OpenMRS documentation? What else?
  • What OpenMRS documentation/information resources do you think are missing for people like you?
  •  What do you think are the biggest challenges in keeping OpenMRS documentation and information up-to-date? And in keeping people engaged in documenting things they discover/change/update?
  •  If we worked on only one part of OpenMRS documentation, what would you want us to improve?

I conducted the first of these interviews today; here’s a very brief summary of the major ideas.

  • simplicity, consistency and clarity: in both content and organization, OpenMRS documentation needs to be more streamlined. Difficulty in finding information is just as daunting as difficulty in understanding information, especially for new users.
  • keeping things fresh: without a strong central presence in documentation, things become easily outdated and obsolete. Structure might change or information might move to new places with no record, or simply never be updated. This can be very confusing and even offputting, as it might seem that no-one is working in a specific area (when in reality they just might not have updated the documentation or created a new place for the information, or mentioned it on a mailing list but not the wiki, etc.)

I’m excited to see a range of OpenMRS experience, from newbie to veteran. Every perspective should provide valuable insight into addressing the documentation dhallenge. (Readers: if you are interested in participating or know someone who might be, please get in touch! evoeges [at] openmrs [dot] org.)