Review notes from codelab

[jmandel]

Just took a quick pass through the rendered codelab content -- really like how this is coming together! Some notes / thoughts below... (I figured it was easier to share everything in one place for now rather than discrete comments, since this is all still just coming together and might get re-organized along the way.)

---

Meta:

• Is it possible to customize the fragments like "/Round 2 codelab review #3" so they use words, or so they use numbers that match the step numbers? the off-by-one (zero-indexed URLs, 1-indexed labels) is consistently confusing me ;-)

• What's the relation between the demo app as it exists in master and the demo app as it exists the in v3.0 tag? It'd be good to make sure these stay in sync (and ideally, to figure out a way to prevent them from getting out of sycn -- maybe just use master branch instead of the v3.0 tag, or maybe separate out the codelab docs from the demo app itself?

---

https://microsoft-healthcare-madison.github.io/demo-auc-app/#0

Time estimates: I see "2 to 4 hours" and also "265 min"

"npn" should say "npm" or "nvm". Might say "JavaScript in the browser and in Node.js, and the express Web framework for Node.js.

"but please feel free to share" --> "and please feel free to share". Better still provide a github PR link or method to share. Might also add a "Getting in touch" section to list Zulip chat (relevant channels) in addition to the "Report a mistake" link (which is great!).

"CDS Hooks" -- we should use consistent capitalization / spacing throughout (in text and in the sidebar step names)

---

https://microsoft-healthcare-madison.github.io/demo-auc-app/#1

In "Skip ahead" and "Warp ahead" sections, consider linking directly to the relevant tutorial pages ("Write a CSD hook")

Under AUCs and PLEs: consider linking to a couple of sources of guidelines, as examples. Like, a deep link to headache guidelines from Intermountain + ACR.

a QCDSM must use more than one published set of AUC in their software

Oh, that sounds like a pain (and I totally didn't realize). Can you share a citation for this?

they must also be consulting a guideline app.
Might just say "consulting guidelines for appropriate use" (to avoid the app-vs-service distinction at this point).

By using CDS Hooks, the EHR can provide a link to the guideline app as soon as it's relevant (like when selecting an order for advanced imaging, before signing the order).
Might say "EHR can consult a guideline service automatically, as soon as it's relevant -- sharing results or a link to the guideline app if further interaction is needed." Again, just want to make sure we highlight that CSD Serviecs can support systemActions (since this was the only real improvement we needed to make beyond CDS Hooks 1.0), in support of PAMA.

"To enable those applications to update the currently draft"

Say "current draft" (no "ly").

---

https://microsoft-healthcare-madison.github.io/demo-auc-app/#2

The embedded glitch app shows me a login screen. It'd be good to explain this above the box so a user knows that this isn't a Glitch.me (or whatever) login screen, but part of the app. In addition would be good to "brand" the embedded app so it says "CDS Demo Login" or whatever.

Am I correctly inferring a kind of "contains" relationship between (3) and the following (4)-(10)? IS it possible to capture this in the codelab nav structure? I'm having trouble with the level of detail in teh outline: what's the goal of this page? I think you can solve this with just a bit more narrative and context. Like, "We'll be developing an set of services in three steps. Imagine our starting point is the following web app, which provides guidance but is cumbersome to use..." etc. For each step, clearly state the problem that we'll be solving. Maybe something like:

SMART Launch

Problem: remembering an external CDS portal is hard; signing in and hand-entering patient demographics wastes time and is error-prone.

Solution: You will add SMART launch...

(and so on for the following steps)

Re: FAQ, is the messaging here correct? Does Epic support SMART Web Messaging, Scratchpad,etc?

---

https://microsoft-healthcare-madison.github.io/demo-auc-app/#3

Re: node versions, can you check that it works with node v12 (the LTS version)? Would be good to target long-term releases whenever the feature set meets our needs.

https://microsoft-healthcare-madison.github.io/demo-auc-app/#4

rate the following combinations of demographics.

Add a header to this table (not obvious that the 1st column is ages, for example).

This site can't provide a secure connection.

Might help to include a quick note that "This demo app is designed to run without a secure connection" or something.

---

https://microsoft-healthcare-madison.github.io/demo-auc-app/#5

the app will be able to securely read data from the EHR using the credentials of the clinician (through OAuth2 openid connect).

Just so nobody thinks the app is going to traffic in passwords, maybe better to say "the app will be able to securely connect to the EHR via OAuth 2, including single-sign-on via OpenID Connect.

I love the explanation about how the provider won't need to remember a separate username, etc.

Consult the link above, and create a launch.html endpoint.
Confused? Part of the goal of this codelab is to get you familiar with using the documentation, so there will be minimal hand-holding throughout.

I like the concept here, but in practice I don't think this is really fair or likely to succeed, given the level of hand-holding on the simplest, well-docuemnted thigns up to this point. Like, you've gone from explaining how to type "npm" in to the command line to... pointing folks to a set of docs we know is hard to read. Now, if you want to submit a PR to the SMART docs so they contain the explanations you need, that'd be fine -- or otherwise, embedding content here will get the job done.

EXERCISE: Visit the site and enter the path to your launch.html endpoint.
Would be good to walk through the key settings in the launcher (like, guiding developers to an EHR launch with EHR framing around it).

Will you add git checkout commands to show how to skip ahead to the pre-written code? And maybe a link to a relevant diff on gh?

---

https://microsoft-healthcare-madison.github.io/demo-auc-app/#6

Will you add git checkout commands to show how to skip ahead to the pre-written code? And maybe a link to a relevant diff on gh?

---

https://microsoft-healthcare-madison.github.io/demo-auc-app/#7

Will you add git checkout commands to show how to skip ahead to the pre-written code? And maybe a link to a relevant diff on gh?

[barabo]

Josh, thanks for the review! I'll try to address all your comments in multiple replies, and maybe you can whittle down your comment text (or use strikethrough) so I don't miss anything as I go - I may address some topics out of order.

[jmandel]

Great -- and you should be able to edit my comment and apply strikethrough directly if you prefer (as a repo owner).

[barabo]

https://microsoft-healthcare-madison.github.io/demo-auc-app/#0

Time estimates: I see "2 to 4 hours" and also "265 min"

Yes, this needs refinement. 2 to 4 hours was the original goal, and I think it's still accurate, but each section uses a Duration: XXX estimate and the codelab framework sums those up based on how much material is 'ahead' of you.

"npn" should say "npm" or "nvm". Might say "JavaScript in the browser and in Node.js, and the express Web framework for Node.js.

Thanks! I appreciate the wording suggestions!

"but please feel free to share" --> "and please feel free to share". Better still provide a github PR link or method to share. Might also add a "Getting in touch" section to list Zulip chat (relevant channels) in addition to the "Report a mistake" link (which is great!).

I've added a wiki, and a section on contributing, which links to the wiki. The landing page of the wiki has a section about 'how to contribute' which hopefully will guide people to the right places.
https://github.com/microsoft-healthcare-madison/demo-auc-app/wiki

"CDS Hooks" -- we should use consistent capitalization / spacing throughout (in text and in the sidebar step names)

Thanks, again.

[barabo]

https://microsoft-healthcare-madison.github.io/demo-auc-app/#1

In "Skip ahead" and "Warp ahead" sections, consider linking directly to the relevant tutorial pages ("Write a CSD hook")

I spent an unfortunate amount of time trying to figure out how to make this work a while ago. Eventually I gave up. The problem I saw was that the links I created did take the user to the linked page, but then something immediately returned the user to the original page. I'll give it another quick try, but it might just be a limitation of the framework that needs developer attention at the source (in googlecodelabs/tools). The good news is that I've been working with them recently and they have been responsive to my issues / messages in the community.

Under AUCs and PLEs: consider linking to a couple of sources of guidelines, as examples. Like, a deep link to headache guidelines from Intermountain + ACR.

a QCDSM must use more than one published set of AUC in their software

Oh, that sounds like a pain (and I totally didn't realize). Can you share a citation for this?

It's covered in pages 4-5 here, although I feel like it's a bit of a gray area. In the documentation it says that a QCDSM must "be capable of incorporating AUC from more than one qualified PLE" and also "have processes in place to update, modify, or remove AUC under specific timelines".

Anyway, I'll link to the document in the codelab here.

they must also be consulting a guideline app.

Might just say "consulting guidelines for appropriate use" (to avoid the app-vs-service distinction at this point).

Yep, that sounds good.

By using CDS Hooks, the EHR can provide a link to the guideline app as soon as it's relevant (like when selecting an order for advanced imaging, before signing the order).

Might say "EHR can consult a guideline service automatically, as soon as it's relevant -- sharing results or a link to the guideline app if further interaction is needed." Again, just want to make sure we highlight that CSD Serviecs can support systemActions (since this was the only real improvement we needed to make beyond CDS Hooks 1.0), in support of PAMA.

I like that, thanks.

"To enable those applications to update the currently draft"

Say "current draft" (no "ly").

Thanksly!

[barabo]

https://microsoft-healthcare-madison.github.io/demo-auc-app/#2

The embedded glitch app shows me a login screen. It'd be good to explain this above the box so a user knows that this isn't a Glitch.me (or whatever) login screen, but part of the app. In addition would be good to "brand" the embedded app so it says "CDS Demo Login" or whatever.

Yep, I think I used this page to prove that I could embed a glitch app and I didn't then do enough to weave it in to the narrative. I'll do that.

Am I correctly inferring a kind of "contains" relationship between (3) and the following (4)-(10)? IS it possible to capture this in the codelab nav structure? I'm having trouble with the level of detail in teh outline: what's the goal of this page? I think you can solve this with just a bit more narrative and context. Like, "We'll be developing an set of services in three steps. Imagine our starting point is the following web app, which provides guidance but is cumbersome to use..." etc. For each step, clearly state the problem that we'll be solving. Maybe something like:

I think it's mostly fair to look at it that way. Perhaps I can break this step into two - the first outlines the intent of the following few steps and the second focuses on the problem of making the SMART Launch work. But I don't know if this slide 'contains' the entire remainder of the slides.

SMART Launch
Problem: remembering an external CDS portal is hard; signing in and hand-entering patient demographics wastes time and is error-prone.

Solution: You will add SMART launch...

(and so on for the following steps)

Makes sense to do it this way.

Re: FAQ, is the messaging here correct? Does Epic support SMART Web Messaging, Scratchpad,etc?

I can't find evidence to support the claim that Epic supports SWM, so I'll retract that until I can.