Efforts toward documentation and training


(Andrew D Oram) #1

At some point we have to consider documentation and training. In fact, we already have faced this in a small way: we have needed text to welcomes new participants to this forum and to define terms of service, governance, etc. The need for documentation and training will spike as we create code and start real-life projects.

We can draw on a lot of existing material about OpenMRS, but it has weaknesses that I’m told are freely acknowledged (and I reviewed it myself a couple years ago). I’d like to propose a way of thinking about documentation and training that can help us make the most of our limited time and resources.

Please let me know what you think of the approach in this posting and where you’d like the effort to go.

Basic principles

Most users don’t like documentation. They get help through searches that turn up isolated answers to specific questions, often in the form of informal messages on forums like this one, or blog postings. Both quickly get out-dated. New people also ask questions on forums–which generate more informal postings.

We need to make extensive use of the informal postings generated out of spontaneous generosity by the community, and enhance them to make them more long-lived and valuable. We also must consider all available media, such as video.


The first task is to make search on our forums as powerful as we can. Smart searches, such as ones that recognize synonyms, would be wonderful, but these require complex tasks such as defining ontologies. If we can just get a search that ranks postings well by relevance and (using the “heart” or “like” feature) quality, we’ll be off to a good start.

Upgrading postings

Considering that the easiest way to get content is through responses to questions or spontaneously written blog postings, we should find the ones that the community seems to consider valuable (perhaps through “likes” and perhaps through human selection) and turn them into something more permanent. The difference between most informal postings and documentation of lasting value include:

  • The documentation is promptly updated when needed, and errors are promptly corrected when discovered. (Of course, this is an ideal, often unfulfilled.
  • Informal postings assume that readers know a lot of context related to the time and topic they cover: readers should know the particular software module and version being discussed, what the current problems are, and what the goals are. All of this context may be lacking when a forum member finds the posting months later, so it should be explicitly added to form lasting documentation.
  • Documentation is usually in a known, trusted place such as a wiki or manual. Because it’s actively maintained and officially blessed, documentation is trusted more.

I’ve explored some of these principles in an old article.

How can we upgrade the most useful postings to trustworthy documentation? Someone has to monitor popular postings and contact their authors to recommend upgrading. We also need guidelines in how to upgrade the postings: suggestions for how to identify missing context, for instance.

Keeping documentation up to date is also a much bigger job than throwing in a new option from a menu or command line. Someone who knows how Libre Health is used must regularly go over the documentation to determine where it describes old ways of doing things, and should be changed to describe new ways.

Documentation diversity

Although it’s nice to offer people a manual, perhaps by working through FLOSS Manuals as OpenMRS has done, other ways to invest resources may have bigger pay-offs. As mentioned earlier, many people are too impatient to read the manual. And it’s easier to ask people to upgrade informal postings on blogs or other places than to funnel all their contributions into a central manual or wiki.

We should recognize useful blog postings, videos, and other content from community experts and link to them. We should suggest further readings for people who finish a piece of content. The resulting labyrinth of documentation and training materials may match up better with the way people tend to learn online: they learn a little, try out what they know, and return with more questions.

(Michael Downey) #2

This is awesome Andy! I think that we can even leverage our existing Discourse instance in a few creative ways to bootstrap these ideas in the short term.

I am going to think a little bit on this and reply later today to extend some of your ideas into possible approaches. Meanwhile let’s hear others’ feedback! :slight_smile:

(Michael Downey) #3

I agree. One way that the Discourse community has used their own platform to do this for their own community is by making good use of moderation techniques: re-categorizing, merging posts into related topics, tagging, re-writing subject lines, etc. There are also “Howto” categories for frequent tasks, and also “wiki topics” that allow anyone to edit the lead post within a topic (or reply to it). I think these approaches could be a good first start at maintaining some rudimentary documentation outside of the traditional “manual” or “book” approach discussed later.

For OpenMRS, I created a Google Custom Search site at http://search.openmrs.org/. This is both free and rather powerful and does allow admins to create things like synonyms, filterable labels, etc. Perhaps play around with that search (in the state that it is!) and see if it seems like it could be useful. The Discourse internal search is somewhat weak, but does attempt to do relevance-based searching.

Google seems to do a great job at indexing Discourse site content. A lot of the relevance, though, comes down to good page (topic) titles and ensuring questions are asked clearly (and editing them if not). I tried to do much of this in the OpenMRS Discourse instance, but it was a significant effort and many people need to be continually engaged in it. (A recurring shortcoming within the OpenMRS community.)

I agree 200%. We could create a “FAQ” or “Best Of” category for this content, and moderators could move topics there. It’s also worth noting that it’s super easy to embed a YouTube or other video in a post – just put the URL on a line by itself. With a line or two of context and a good title, you can easily create a video library. (Even in its own category if there are enough videos!) Block quotes with links, embedding Stack Overflow posts, etc., could all be done in a similar way.

I tend to agree with this prioritization. A manual would be good but is maybe not the first priority. If we do create a manual-style documentation project, I would encourage us to create and maintain the content in git or another VCS using Markdown or similar syntax, and then use one of the many frameworks available for formatting, rendering, and display.

What do others think about Andy’s ideas? :slight_smile:

(Andrew D Oram) #4

Yes, let’s here from others out there. It’s exciting to see that you and I have similar thoughts and conclusions, Michael. I did a few searches on the http://search.openmrs.org/ site and found it quite powerful. There’s a lot of documentation, and relevant things seemed to turn up. There’s even auto-completion. But I didn’t see any synonyms turn up. For instance, I searched for “drug” and then for “medication” and each turned up documents containing that term, but they weren’t linked. That was just one isolated experiment, though.

(Michael Downey) #5

I don’t think we ever did many if any of them. However, it is supported: https://support.google.com/customsearch/answer/2631030?hl=en

(Tony McCormick) #6

This article about Linux installation instructions and typical Windows users is quite relevant to providing models of documentation that are effective.

Or at least what NOT to assume…

(Harley Tuck) #7

Hi Folks-

I’m looking at how to organize those training videos Tony mentioned from the meeting last week. He suggested they be grouped with a clinical and a HIT/ research focus, which makes sense to me. I’ve got a firm grip on the clinical content: workflows for the healthcare staff or things the office staff does that involves patient activities (add new patient; enter med histories, etc) and should include for the Office Mgr types, the facility/ practice setup.

However, I’m having trouble putting my finger on exactly what the HIT/ research content would be. Is it strictly about how to extract Libre’s data for research? Because if that’s all it is, the prefab reports that come with the EHR aren’t versatile enough to use for research so they’d need to pull what they really wanted directly from the database. And just showing/ talking about the database structure is not particularly suited to a series of video presentations, unless I’m supposed to walk them through installing phpMyAdmin or give them an intro DBA lesson on cli mysql? Which I would imagine/ hope they should get in one of their database classes, not the ehr class.

How do people feel about the HIT/ research focus be guided by the premise that those students are being trained to be the IT person hired to run the EHR for some practice. That way they could do things like setting up the procedures module, making the rules for CDRs, customizing the calendar and the flow board etc. THOSE workflows would make great videos and could include in each segment where to find the data in the database if research on that content was desired.

Rgds- Harley

(Tony McCormick) #8

@rhoyt what do you need for your students?

(Bob Hoyt) #9

@tony @htuck @yehster @teryhill I don’t think we are ready for a research video yet. If we can improve reporting that includes csv output then perhaps we will be ready for some descriptive and visual analytics.

In the meantime, the entire project would benefit from straight-forward how-to videos that Harley describes. These would be similar to the ones done for OpenEMR. My first impression would be one video for instructors trying to set up a clinic and learn to use the admin functions. The second would be a general orientation of common features and the third would be a deeper dive into more detail

(Harley Tuck) #10

@rhoyt - The functional groupings of the user training videos you mentioned correspond to the organization I used for the OpenEMR vids I made: do them by workflow, and identify who’s likely to use them: line staff users like Front Desk or Providers, or an admin/ manager type.

The staff user videos would be simply how to perform the workflow and just enough explanation of the process that they can make appropriate choices when needed. The admin content would have the module configuration workflow, and how to troubleshoot problems.

As of today, I have already posted the first of the 2 overview videos and have the second all but ready to put on the Libre YT channel but I keep getting interrupted… For the rest of the clinical tutorials, I will continue making them in an order that seems reasonable to me: the admin/ config of the workflow module, then the user workflow. How does that sound?

I was going to start with the facility setup, then adding patients, then a sample encounter. Just those activities will turn into appx 10 videos of 10 - 15 minutes ea, to get started with, which will be a good library of the clinical fundamentals. But of course Libre does so much more.

Anybody have observations/ suggestions for a different production plan? I have no agenda about the order to do these; whatever would serve the Project best. E.g., considering Libre’s target audience, do you folks see a need for custom service codes so providers can enter clusters of services and their associated diagnoses into the fee sheet all at once instead of searching for and entering each one individually?

When we get this agreed upon I will post a proposed list of videos, or write up a formal proposal, whichever’s wanted.

Rgds- HT

(Bob Hoyt) #11

@htuck @tony

I do like the first Video you posted on YouTube.

Looking at the ones you did on OpenEMR I do think you need one for 1. Setting up a clinic 2. Entering a new patient 3. Creating a new encounter 4. How to use the calendar 5. How to order a med and a lab 6. Basic billing 7. A CDR video would be very good

Do you have an idea as to how much $ support you need per video?

(Robby O'Connor) #12

We can also use Google Code-In to produce these videos.

(Tony McCormick) #13

No we can’t @r0bby, this requires someone that actually knows both clinical work flow and the EHR very, very well. @htuck will do this.

(Tony McCormick) #14

@rhoyt I’ll have a SOW to you by tomorrow morning.

(Kevin Yeh) #15

+1. These need to have professional level production values as they are going to be useful for both instructional purposes and as “advertising” to institutions.

(Robby O'Connor) #16

Alrighty… Jus an idea…