Redesigned new encounter form with help file #1572

zbig01 · 2018-04-23T05:34:29Z

interface/forms/newpatient/common.php
interface/forms/newpatient/common_help.php

minor addition to flat stylesheets

New Encounter Form

Help Modal

below by bradymiller:
Up For Grabs demo for this PR is here:
https://www.open-emr.org/wiki/index.php/Development_Demo#Delta_-_Up_For_Grabs_Demo

interface/forms/newpatient/common.php interface/forms/newpatient/common_help.php minor addition to flat stylesheets

bradymiller · 2018-04-24T09:38:33Z

Set up an Up For Grabs demo for this PR here:
https://www.open-emr.org/wiki/index.php/Development_Demo#Delta_-_Up_For_Grabs_Demo

mdsupport · 2018-04-26T17:22:06Z

In general it is a good idea to have context sensitive help throughout application - probably as part of menu and not the individual screens. Logic would be to offer screen specific help if present otherwise start with a overview which contains navigation to next level. It also may be overkill to translate help documents one sentence/phrase at a time. How about following ippf documentation template? Then documentation will have language as major node -- ippf can be treated as a 'language'.

zbig01 · 2018-04-27T07:38:00Z

Providing a system wide context sensitive help is a laudable goal to make the application user friendly. This however would require a tremendous amount of work. This approach is an effort to modularize the process and provide relevant help where needed. By linking the help to the particular page the user receives the needed information without having to go searching elsewhere in a detailed document like an instruction manual. This approach would let the user quickly look up use of a particular part of the page they may have difficulty in understanding.

These files have been deliberately created in this fashion for the following reasons:
- Avoiding a TL;DR situation 😃
- Easy to move the sentences around rather than rewriting entire paragraphs
- Easy to add more information
- Would hopefully make translating into another language easier by using a tool like Google Translate

Screenshots to provide visual clues have been left out to ensure ease of maintaining the document through different versions, more so if it will be translated.

Moreover it blends in with the application unlike a link to an external document.

mdsupport · 2018-04-27T23:20:23Z

To clarify earlier post, help file in this PR provides more or less same information as :
Documentation/IPPF_Guides/Process 1-3-0 Creating a new visit Ver 4-0.pdf

Our thought was that by adding few lines of code through an include would enable making documentation available for all screens. An example would be:

..  Main script
    // Set process details
    $myProcess = "1-3-0";

..  Include this common library
    $mytoks = explode('/',substr(__FILE__, strlen($GLOBALS['webserver_root'])));
    $libDoc = $GLOBALS['webserver_root']."/Documentation/".$_SESSION['language_choice']."/$myProcess/".implode('.', $mytoks);
    // Check if this script specific file exists otherwise use a variation of the following
....
    $libDoc = $GLOBALS['webserver_root']."/Documentation/".$_SESSION['language_choice']."/$myProcess/Overview.php( or pdf)";
....
    // Include code below to make the menu link / document icon (whatever) available to `<body>` as an application-wide standard

In our experience, translating a document a sentence or phrase at a time creates more potential problems in the main application (which is the primary purpose of xl functions).

Anyway, since help is primarily an on-boarding accelerator it is matter of limited interest for most sites.
Thanks.

bradymiller · 2018-04-28T08:32:37Z

Just going to weigh in on the translations issues. It's very tough to get folks to translate and adding another mechanism (than just the translation spreadsheet) would likely mean that the stuff in the Documentation directory would:

likely never be translated for the public project
and even if translated, would then likely never be updated

The nice thing about the xl mechanism here is that it's in the same pipeline for the translators (ie. translate them in the google doc translation spreadsheet) and if the help documentation ever got updated, then it will force the translations to be re-updated. Agree that it is tougher since things on the spreadsheet are "out of context" but the above advantages do outweigh this issue.
-brady

robertdown · 2018-05-03T05:27:20Z

I think in-program help is not something we can maintain; as Brady said translation would be a nightmare. This kind of help doc is better suited for the wiki (Or the new shiny and pretty docs system coming soon)

bradymiller · 2018-05-03T06:58:20Z

@robertdown , @zbig01 ,
To clarify my post. The way @zbig01 has it now will work fine for translations. Since it will go into the openemr translation pipeline (ie. will get translated) and any updates to it will force re-translation. I meant to state that creating another mechanism for translation (ie. a separate help doc for each language) will likely get no translations; additionally, even if it did, the translations would never likely get updated. To see how nicely this works, check out zbig01's help document in the Administration->Acl form that is in the current codebase. This basically makes the ACL module that essentially nobody understands into a form that is very understandable.

robertdown · 2018-05-12T21:29:36Z

I'd still prefer to not embed help docs - or if we do, they should come out of the new docs system, maybe we write an build command that brings them into the codebase. Single source of truth for help docs is imperative. Otherwise we'll quickly fall into even more outdated docs

bradymiller · 2018-05-12T22:16:05Z

It is rare that we have a developer create documentation, and even more rare if we mandate a specified format :)
(in this case for a complicated script, again, this is relatively easy to maintain, translate, and even remove if it becomes burdensome)

zbig01 · 2018-05-13T05:48:05Z

I approach the problem as a user first and developer second. I note the cogent arguments being advanced against this feature. From a practical viewpoint during the course of a single workday I have to use multiple different EMR's Epic, Cerner, openEMR and various PACS systems to get the job done. Keeping up with the multitude of changes that is introduced in each of these systems is a highly frustrating experience.
While as a developer one is intimately familiar with the code and the features that it generates the user approaches it from the features side and is hardly bothered by the code. Saving even a few seconds of a user's time is invaluable and will be much appreciated. This feature has been deliberately added to fulfill this requirement.
There are numerous articles that have been published about the EMR and physician burnout
AMA Article
NEJM

The added benefits of this feature it is easy to change and edit, quickly amenable to translation and if a new feature is added a couple of lines can be added or modified from the existing help file to keep it current.
In fact before committing a PR the administrator could insist on updating the help file.
I feel this modular approach has merits when compared to a monolithic approach.
Please do not misunderstand me, a centralized repository of files is needed and will be extremely valuable, I wonder how easy would it be to maintain let alone translate.

robertdown · 2018-05-13T06:49:12Z

@bradymiller - Yes it's rare, but it's not a free for all; having a system in place is important.

@zbig01 - A centralized repo already exists in the form of the wiki. Currently that's not easily translatable, but our upcoming rebuild will have translation built in, so it'll be easy for people to contribute a translation. But I can't expect a documentation writer to be able to traverse the codebase.

I'm really against putting help files in the codebase, it sets a bad standard. Help documentation belongs on the wiki.

bradymiller · 2018-05-13T08:12:37Z

hi @robertdown ,
If you provide an option that is equivalent or better to what is already proposed here, then go for it. This current solution does the following:

provides documentation for the script use
provides easy mechanism (ie. code review) to enforce updating doc when change script
provides automatic mechanism for translations
provides automatic mechanism for translations when the doc is updated (this is a key point)
was built by an end user to improve usability

(and if we ever have a system in place that will support this in the future, then I would be happy to copy/paste/remove this doc into that new system in the future :) )

robertdown · 2018-05-13T23:32:43Z

It’s not about a better system for in-code docs, it’s about not putting documentation in the codebase.

bradymiller · 2018-05-14T06:47:12Z

Related ongoing forum thread can be found here:
https://community.open-emr.org/t/documentation-and-codebase/10125

bradymiller · 2018-05-14T06:47:38Z

oops on the 'close and comment', just re-opened :)

bradymiller · 2018-05-14T13:13:50Z

This PR has been updated and migrated to the following PR:
#1631

Redesigned new encounter form with help file

b622023

interface/forms/newpatient/common.php interface/forms/newpatient/common_help.php minor addition to flat stylesheets

bradymiller added the Status: Needs Review label Apr 23, 2018

bradymiller self-assigned this May 11, 2018

bradymiller closed this May 14, 2018

bradymiller reopened this May 14, 2018

bradymiller closed this May 14, 2018

bradymiller mentioned this pull request May 14, 2018

Redesigned new encounter form - take 2 #1631

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Redesigned new encounter form with help file #1572

Redesigned new encounter form with help file #1572

zbig01 commented Apr 23, 2018 •

edited by bradymiller

bradymiller commented Apr 24, 2018

mdsupport commented Apr 26, 2018

zbig01 commented Apr 27, 2018 •

edited

mdsupport commented Apr 27, 2018

bradymiller commented Apr 28, 2018 •

edited

robertdown commented May 3, 2018

bradymiller commented May 3, 2018

robertdown commented May 12, 2018

bradymiller commented May 12, 2018

zbig01 commented May 13, 2018 •

edited

robertdown commented May 13, 2018

bradymiller commented May 13, 2018 •

edited

robertdown commented May 13, 2018

bradymiller commented May 14, 2018

bradymiller commented May 14, 2018

bradymiller commented May 14, 2018

Redesigned new encounter form with help file #1572

Redesigned new encounter form with help file #1572

Conversation

zbig01 commented Apr 23, 2018 • edited by bradymiller

bradymiller commented Apr 24, 2018

mdsupport commented Apr 26, 2018

zbig01 commented Apr 27, 2018 • edited

mdsupport commented Apr 27, 2018

bradymiller commented Apr 28, 2018 • edited

robertdown commented May 3, 2018

bradymiller commented May 3, 2018

robertdown commented May 12, 2018

bradymiller commented May 12, 2018

zbig01 commented May 13, 2018 • edited

robertdown commented May 13, 2018

bradymiller commented May 13, 2018 • edited

robertdown commented May 13, 2018

bradymiller commented May 14, 2018

bradymiller commented May 14, 2018

bradymiller commented May 14, 2018

zbig01 commented Apr 23, 2018 •

edited by bradymiller

zbig01 commented Apr 27, 2018 •

edited

bradymiller commented Apr 28, 2018 •

edited

zbig01 commented May 13, 2018 •

edited

bradymiller commented May 13, 2018 •

edited