Documentation and Codebase

OpenEMR Development
#1

I wanted to bring this to the forums as we don’t really have any kind of policy on it.

Currently in the codebase we have a toplevel folder called Documentation where some of the docs live. We also have the wiki. There are also some scattered help docs throughout the codebase.

I think now is a good time to really begin the consolidation process of the documentation. I suggest we evaluate the files under the top level Documentation folder (With the exception of the INSTALL file, most of that folder hasn’t been touched in years) and either make a plan to migrate them or just remove them. Same for the help docs throughout the codebase.

The thought here is we need a single source of truth for documentation - fracturing the documentation means a harder road for maintenance and could lead to easily outdated documentation. The new Drupal system will be multi-lingual which allows for translations. If we wanted to embed the documentation into the codebase we could write a pipeline to export from Drupal and format it to something we could embed.

My recommendation is no inline documentation in the codebase/UI and instead comprehensive documentation on the website.

For the sake of clarity - I think inline documentation is a bad idea. Most modern products I see don’t do much inline help/docs, instead they point to their website (PHPStorm is an example of this). Additionally, by placing the docs in the codebase we make it harder for documentation creators to contribute. Instead of logging into a user-friendly website and submitting translations, writing guides, or providing how-to documents, they would have to successfully install OpenEMR locally and learn how to traverse the file hierarchy just to contribute documentation.

Documentation writers should not have that burden, let’s keep the bar low for docs contributions.

#2

openemr-devops is currently a big pile of repo-embedded documentation. Wanting to slurp it up too? It’s got the full-stack docs…

#3

I think the documentation in devops is ok for now, but yes, I could see a time where we’d migrate it over (But I don’t see that need anytime soon).

The main feature set is so big putting documentation inside the codebase would be unmanageable.

#4

Hi,

In theory this is great. But there are scripts where inline UI documentation works well. For example in the Administration->ACL page, if hit the ‘?’ tooltip on that page, it shows the following:

Are you basically stating that these pages are not allowed and should be copy/pasted to the wiki (where most users will no longer see them, where developers will no longer update them when make changes, and where chance of translations will basically be almost zero)? Since this does appear to be the recommendation in the ongoing PR here and main reason for this thread:
Redesigned new encounter form with help file by zbig01 · Pull Request #1572 · openemr/openemr · GitHub

Rather than creating rigid rules for documentation out of the gate, recommend:

  1. Maintaining flexibility until an actual new document engine/plan is practically in place
  2. Continuing to stress/weight the importance of Usability

thanks,
-brady

#5

Hi,

And on the separate issue of cleaning the Documentation folder, completely agree; recommend checking out this wiki page where this was done in the past:
https://www.open-emr.org/wiki/index.php/OpenEMR_System_Architecture#Resources_included_within_the_OpenEMR_package
(to clarify, note the outdated docs were removed and the links simply direct to where they were in an older codebase)

-brady

#6

It may be good to have a clear understanding of the audience for documentation.

In our experience, documentation is used primarily during on-boarding of new employees who are familiar with other EMR/EHR/Billing systems. From that perspective IPPF type of process documentation is very useful.

We also find that after a week or two on the job, documentation is rarely accessed by the staff. So putting an omnipresent element is a waste of valuable graphic real estate.

Our suggestion would be -

  1. Let every script declare its document key and optionally a parent collection in case the doc page is under development / not found.
  2. Use globals.php to add documentation links for active pages.
  3. Use settings to specify documentation root (in-house / cloud) with language selection as sub-directory.
  4. Use site’s documents directory to override standard documentation if administrator goes through effort of developing custom documentation for specific keys.
  5. Exclude all documentation from standard installation.
  6. Use Google Translate APIs to batch translate all pages to all supported languages.
  7. Provide instructions for administrators to copy language specific documentation to local server if they cannot rely on documentation in cloud.

Useful links:

  1. Google cloud for non-profits
  2. Translate Documentation and PHP Code
  3. Translate “New Encounter form” to selected language
#7

In my experience, long wordy helps are best left out but, useful in application are quick one or two sentence bullet points or tips in a panel.

#8

I agree, bare-bones minimal for anything in the code (Think tooltips) and plenty of expanded documentation on the external system

#9

hi @robert.down , @sjpadgett , @mdsupport ,

I need practical guidance on this (or this will slow down review process for several related PRs). Should we then remove the instructions in the ACL screenshot above? The developer, @zbig01 , whom is basically rewriting many of the scripts to be bootstrapped and responsive is writing this documentation for the more complicated scripts; should he not be doing this? If he doesn’t do this, are we losing out on a opportunity for documentation?(note we only get nice documentation written for OpenEMR once in a blue moon, and I’d like to avoid missing out on this opportunity)

Given limited resources, there are really only 3 options at this time:

  1. Don’t write the documentation
  2. Do as we are doing currently, and allow @zbig01 to include in the help modals
  3. Send the documentation to the current wiki (assuming @zbig01 would even think docs in this form would be worth his effort)

(please avoid any other options that are not currently in existence :slight_smile: )

thanks,
-brady

#10

Considering this is just discussion, until all the pieces are in place it may be better to continue current development track. Since there are relatively few screens with @zbig01’s approach (I think there was one with patient search), it will be relatively easy to migrate the final work product to another platform.

1 Like
#11

I’d say number 3, no point in continuining to pile on additional work of porting if he can just put them in the wiki.

@d3sandoval and @MatthewVita any thoughts on this?

#12

Anywhere you put them will require “porting”, so that is not a concern here.

If place @zbig01 's nice docs in wiki now, then they now need to be ported from html/php to mediawiki and then in future from mediawikia to whatever we use; additionally, these docs will then be out of sight and mind on the wiki with the hundreds of other documents (ie. will not be used by majority users and will be waiting on some not yet existent mechanism; and likely also will result in much less motivation to produce this documentation in the first place).

Versus, if keep them in the codebase as help modals, then in future can port them to whatever mechanism we use.

#13

As long as it’s clear in the wiki as to what version the documentation is referring to, i’d prefer it to live there. When docs live in the code, they tend to not get updated as much due to:

  1. developers wanting to just contribute code, not words, to the software
  2. reviewers not wanting to block PRs due to a lack of updates to documentation
  3. non-devs wanting to update the docs not having the git-fu necessary to update docs

I mentioned in @robert.down’s Documentation Migration Strategy that “In the future, i hope that we can provide this documentation as a part of the user’s workflow.”

An easy bridge between in-line help and docs that live on mediawiki is a target="_blank" href that opens up the relevant feature documentation.

Edit: grammar

#14

“As long as it’s clear in the wiki as to what version the documentation is referring to”

Therein lies one of the many OpenEMR documentation issues. The wiki is basically chaos meets even more chaos.

#15

Do note I am not recommending that all documentation go into the codebase (agree that is what external documentation is for). @zbig01 's stuff is a special case that is happening at a special time.

#16

Port them now or don’t bring them in at all, I don’t want to set a standard for adding new docs to the codebase. We are actively working on fixing the chaos in the wiki, no need to creating even more work.

I really, really don’t want to put anymore documentation in the codebase, even zbigs stuff

#17

I guess I really, really want front-end high quality documentation to improve Usability and am willing to temporarily compromise from the perfect world backend processes/structure to get there :slight_smile:

I don’t think the answer is to turn away differing documentation methods because of a little increase in workload down the road (note this discussion thread has more posts in it than there will even be help modals in the code…). I would be happy to simply spend a couple minutes copy/pasting and converting to standard markup down the road on documentation that likely took hours for a volunteer to write. Innovation and improvements sometimes move faster than the ideal codebase architecture can support, which in the end will lead us to an ideal solution, such as possible popup links (per @d3sandoval ) to the new docs engine when it is ready(or maybe even another process we have not even thought of yet if the new docs engine does not pan out as planned). And at that time when do transition to a standard doc method in the future, there will be some high quality documentation to copy/paste into it (versus awaiting a volunteer for a likely indefinite time to document this from scratch after the shiny new doc engine solution is working).

#18

Let’s compromise - we leave what’s in the codebase as-is for now but not bring in anything else. I think there is 1 pending PR with documentation, let that come in but any more documentation @zbig01wants to do should go to the wiki. This has the benefit of not interrupting work already done while still ensuring a viable single-source of documentation for the future

#19

I just want to comment that using in place modals for help is just not a good idea. A help should, at most, be in a panel that can persist while user can still continue workflow. Otherwise user is popping up and down modal. Also it is not the modal by itself that makes for responsiveness but its content. Lastly on modals, we should move away from using them so liberally and get rid of them where we can instead of adding them. Modals on portable devices become cumbersome.
I think MD Support was on a right track and to generalize we could develop a master help script that is called with a token that points to the help content where ever it may reside and deal with the formatting in the script. This would also make for an easier context based help. A universal panel could companion the content script. This make for much easier integration and dealing with special use case in one place. Tooltips, while useful, become annoying when you have too many.
Helps are like a box of chocolates! Gump circa 1994.:slight_smile:

#20

+1 for overlay help content in the future. What we do in the meantime is up to the reviewers of the PRs in question.

Also, apologies for taking so long on the documentation that comes with User Interface Design Style Guide - The Beginnings - there’s a lot of code duplication that I’m trying to dig through to prevent unnecessary future work :slight_smile: