Google Season of Docs (SoD)

Hey everyone, my name is Elizabeth!

I’m submitting a project proposal to Google Season of Docs (SoD) in the hope of getting some funding to support OpenEMR documentation. As part of this effort, I’ve been working on brainstorming project ideas. I made a post with ideas here but haven’t had as much input as I’d hoped (shout out to @htuck for responding!). I wanted to reach out in this section of the forum in case it gets more visibility.

I’m going through the wiki documentation and have found it difficult to get up to speed as a new user. Based on this, I’m wondering if restructuring the documentation to be more user friendly (especially for new users & how volunteers can help) and where helpful, adding supplemental documentation may be the biggest value add. I think it would have a bigger impact the ideas I originally listed in the linked post above.

Do you agree that the idea in bold would be a large value add? Is there a different idea that would make a bigger impact?

I’m new to OpenEMR, so I would love to hear your ideas about documentation! My hope is we can target the biggest value add for the community, rather than what one person views as the biggest add.

1 Like

I often times have a hard time finding the info I need in the wiki.

I think the wiki is arranged in a way that is good for technical reference. But not so good for getting information on “how do i do $x”. For example, the configuration of certain features is in a different section then how to use those features. Which makes sense from one angle.

Here is a thought. If in stead of restructuring the documentation. You add a section on “how do i do $x” which contains an ordered series of links to the correct part(s) of the wiki for each task involved.

I know part of the wiki is already written like that but not all of it. In the end, anything you do that is an improvement is well, an improvement over what is there now.


Thank you for your input, D C! A how-to guide is a great idea for how to help new users without interfering with the current structure. Sounds like a win-win with the recent release of V7 since it could cover new features and changes as well!

I forgot to mention, @htuck had an idea related to this that he introduced in a side discussion. Harley recommended listing the steps a new user should take to become acquainted with OpenEMR, in order, with links to the wiki pages that describe them.

I think combining Harley’s outline idea with D C’s how-to idea creates the foundation for a powerful intro doc!

Previous proposals that received funding from SoD also focused on making documentation easier for new users to navigate so I think this project idea has a good precedent.

What do you think about this idea?

great idea @bearzillasquatch
One thing about mediawiki markup is that if the page content is organized in sections with formatted headings the headings serve as url anchors (and incidentally as the lines in a document’s TOC). That way a wiki link to a specific task can go directly to a section instead of only to the document, which would require the user to search through it.

In the case of pages that aren’t organized with headings maybe the editor could get the OK from the author to add them?

  • HT

I didn’t comment as I think a getting started guide is good for everyone. I wonder if even just having some kind of flowchart documentation for OpenEMR providers / admins of making decisions about how to configure OpenEMR.

IE, if you are a sole practitioner – what things should I setup, how should I configure my clinic, how do I get started?

If you are a small clinic – what things should I do, what decisions do I need to make (features turned on or customized) for a small clinic.

Just some ideas.

Thank you for the insight, @htuck! Asking authors for permission to add headings is a great idea. I don’t think I’ll be able to go through all of the wiki articles before the proposal is due so I’ll plan to do this if we receive the funding (!) At that point, we can also decide if restructuring the wiki or adding new overview documentation would be more beneficial, feasible, etc.

Thank you for your ideas, @adunsulag! I’m intrigued by structuring the documentation as a flowchart. Those are great for showing sequential steps and linking actions to specific users.

@adunsulag brings up a great point about different needs between users. I want to ensure I’m not missing a group as I draft the project proposal.

OpenEMR community, is the following list missing any OpenEMR users?

  • Practitioner
  • Small clinic
    (potentially broken down into physician, clinician, accountant, receptionist)
  • Patient
  • Developer

@htuck is there anyway to make a wiki page that directly accesses the data base for the relevant code from a different page? For example, if the new page pulls the contents of an earlier page. Then if the earlier page gets edited/updated, the new page will have those updates too since it’s basically just getting the other pages data from the database? So when the “reference” pages get updates the “how to’s” get updated too. If that’s possible it might make maintaining and updating the documents less daunting.

@elaughlin you have “patient” in the bullet list of users. Are you suggesting that the patient fill out their own charts? I fear that some providers would be on board with that if it meant less work for them.

@bearzillasquatch ,
The wiki has templating. For example, here is a template:
Template:Onc2015 - OpenEMR Project Wiki
and here is one of the places it is used:
OpenEMR Project Wiki

@htuck, @elaughlin ,
If improving wiki documentation, wouldn’t worry about getting OK from prior authors :slight_smile:
Any of the ideas in this thread would be a huge value added, and looking forward to seeing what happens! The only thing I would add is to think about how to future proof the documentation as much as possible (ie. make the future maintenance/updating of the documentation as easy as possible).

@brady.miller that’s what I’m talking about. If the information is only “maintained” in one spot but used every place it makes logical sense. That should lead to more info for the users but not more maintenance by the maintainers.

If i ever figure out how to use oemr reliably i’ll be happy to help with the documentation. I know that’s the least favorite part for software developers.

hi @bearzillasquatch , If you (or anybody else) wants to get a wiki account, just email me at with the username you want and I will then set up a wiki account for you.

@bearzillasquatch I listed “patient” because of OpenEMR’s Patient Portal feature. If clinics choose, they can enable a Patient Portal in which patients log in and fill out information, such as questionnaires. It’s different from the OpenEMR site that professionals access, but I think it’s still useful to acknowledge that patients use OpenEMR too. More information about the Patient Portal can be found here.

@brady.miller Thank you for your input about project ideas! It’s encouraging to hear you think all of the ideas in this thread would add value :grinning:

Based on the feedback so far, it sounds like making documentation more user friendly is the most popular project idea. With the proposal deadline looming (March 24th), I’ll use this idea to move forward with the proposal and focus my efforts on getting that ready for submission. Details about how to update the documentation can be addressed once we (hopefully!) get funding from Google :crossed_fingers:

Thanks for the go-ahead re: correcting others, I’ve been kinda literal in my ideas about that so good to have some parameters :slight_smile:

That ‘intelligent’ wiki page may be feasible to create as a future feature but as far as I know it’s waaay beyond the capabilities granted to normal wiki editors! Sounds like a lot of fun though :slight_smile:

It’s tricky to lump those particular user roles under ‘small practice’ since they would be present in a larger practice also. In my experience a lot of practices will give their staff users (let’s call them) job titles which will often be blends of the default OEMR ACL roles. For e.g., what they title ‘practitioner’ will perform tasks ‘belonging’ to both OEMR’s provider and clinician ACLs. They can get really creative re: the job titles, and one practice’s ‘practitioner’ will usually not perform the same set of tasks as another’s. Since the ACL roles built into OpenEMR dictate a users’s access to different menu items i.e., workflows, would it be workable to base your OEMR user types on them? Although I think having the Dev and Patient user types is a great idea.

Best- HT

Thank you for sharing your knowledge about practices and blended roles!

Sounds like blending the “practitioner” and “small clinic” users into one “clinic” user would make it more applicable. I’m tempted to include “clinic” as a user, explain the different OEMR roles (admin, physician, etc.) under that title, and suggest that practices determine which employees will have which roles. I’ve only explored the “Admin” user on the demo so far, but my initial thought is to include instructions (or links to wiki pages) for all the OEMR roles. Since the division of labor varies between practices, I hesitate to lump similar ones together (i.e. physician and clinician), in case a practice keeps them distinct. It’s great to hear “developer” and “patient” are solid user choices and that I’m not missing others. It’s so fun to discuss users and how to best address their needs via documentation!

Hi @elaughlin
Guess I’m not clear on what you have in mind for your ‘user’ groupings of docs. What would the criteria be for differentiating users?

As far as similarity between ‘physician’ and ‘clinician’ is concerned, there may be a similarity in common usage of the terms, but OpenEMR has them as 2 discrete and different ACLs, with different accesses to OpenEMR capabilities. A ‘Clinician’ performs tasks that a Medical Assistant or a Nurse might do, where (basically speaking) the ‘Physician’ does Doctor stuff which non- MDs are not permitted to do.
Best- HT

I’ve been approaching users as raiders of information - they only want to read what they need-to-know to complete their goals. By breaking the getting started guide into different sections for specific users, I think it will be easier for users to navigate the documentation and find the information they need. This will make users more likely to read and learn from the wiki, rather than giving up or posting in the forum first. (I’m not aiming to dissuade users from posting in the forum, I’m aiming to reduce the number of questions that are resolved by links to wiki pages.)

Jumping off this, Johnson-Sheehan’s approach to technical writing begins by analyzing the needs, values, and attitudes of each user. With this knowledge, documentation can be written in such a way that it addresses the most important, if not all of the, user requirements.

For OEMR’s documentation, I think “needs” is the main requirement because users want to know how to use OEMR to meet their end goals. For a clinic, the user needs to know how to install and use OEMR to run a medical practice. For a patient, the user needs to know how to navigate and use OEMR to meet their medical needs. For a developer, the user needs to know what they can do to improve the OEMR software. So I’m envisioning differentiating users by their needs/end goals.

Based on this, another user we could add is “technical writer” because they need to know which features aren’t covered by the documentation or which areas of the documentation need to be updated.

TLDR; I’m envisioning differentiating users by their needs/end goals so they can easily find the information they need to know rather than becoming overwhelmed or distracted by other information. I’m debating adding “technical writers” as another end user because they have distinct needs/end goals from “clinics”, “patients”, and “developers”.

Idea for a potential new user: “integrators”

My impression is that they would know more about OpenEMR than clinics and patients, but I’m not sure how their knowledge and needs would differ from developers.

1 Like