New Provider Directory + Humana specialist search example

[jdjkelly]

@jamais-vu @mseckykoebel just looking for general feedback on two new articles/examples:

https://docs.sero.run/book/how-to-build-in-health/provider-directory
https://docs.sero.run/overview/examples/humana-hematology-specialist-search

Thinking it would be nice to use GitHub for any questions/idea exploration on these so some of the reaction/questions can be captured in the open.

So, first:

• After reading these do they make sense? Are there narrative problems?
• Does the example work? Can you run it yourself in the project now (it's at examples/humana-specialist-search)

[mseckykoebel]

For this page, my takeaway is that a provider directory is a database of healthcare providers (doctor, chiropractor, and anyone else who can practice) and their roles with regards to what they provide (clinical psychologist is licensed differently than a dentist).

The rest of the document looks good to me, but could the definition be more verbose?

---

For this page, the code on my end runs. On the gitbook page the only annoying thing is the npm update.

What I got from the walkthrough it is that we make two queries: one for the provider directory, and then one for the specific practitioner we are looking for. Code itself makes sense to me and the content printed to the console, for me, is perfect.

As this is an example and not a walkthrough I think it's good, the only narrative changes I would add might make it seem more like a walkthrough. I'll look into some more tonight and fresh tomorrow.

[jdjkelly]

@jamais-vu ping

[jamais-vu]

Provider Directory

I agree with Mason that the provider directory page could be a bit more verbose. The page includes all the relevant info so I'm not sure what to add, but it feels a bit brief.

Humana Hematology Specialist Search

Seconding the npm notification being annoying. Is there a way to enlarge the embedded Replit preview, or is its size fixed by Gitbook? Even if I change the font size, the embedded console contains the same amount of lines. Ideally it would look like the Replit page, which lets me see all the information at once.

Other than that I like the Replit. This example definitely benefits from being able to run the code.

Walkthrough

Overall impression:

As an example it works and makes sense, but I'm not sure if a reader would be able to use this as their only tutorial for accessing Provider Directory APIs (which might not be your intent). I would have to play around with it and reference other resources to get a full understanding - maybe this is what @mseckykoebel meant by "example" vs "walkthrough". Two questions I have:

1. Is it correct that hemotologyQuery searches for PractitionerRoles where PractitionerRole.specialty.text is "Hematology"? Might be worth noting that PractitionerRole.specialty is a CodeableConcept, and demonstrate how to perform a search using a clinical specialty code from the relevant Value Set. For example the SNOMED code for clinical hematology:

const hematologyQuery = {
  "specialty:coding:code": "394803006", // would this be a string?
  "specialty:coding:system": "http://snomed.info/sct/",
  _tag: `${Humana.MedicalDentalNetwork}|${planId}`,
  active: true
}

Or in general another quick example of how the reader might search for a complex type like Coding in addition to a primitive type like string.

2. What level of familiarity with FHIR does the target audience have? Are they FHIR devs who have exposure to FHIR API and are now working with Provider Directories, or general devs with only basic exposure? If the latter, I think there should be a bit more explanation of the search query in step 2.

I like that each line in humana.ts is commented. Makes it easy to connect to what you say in the docs. I also really like that you explain why you use quotes around "specialty:text" because even though the explanation isn't specifically relevant to the example it might otherwise confuse a developer.

Links:

• First line of Walkthough:

  Sero implements an Client that can make requests to FHIR APIs

  The linked page doesn't give much information if I don't know what a Client is. (Should also say "a Client" not "an", can't seem to edit this myself.)

• Second line:

  You can learn more about FHIR and Provider Directories in our How to build in health the easy way ebook.

  Should link to https://docs.sero.run/book/how-to-build-in-health; currently links to https://docs.sero.run/book/how-to-build-in-health/decision-support-apis.

• A bit further when you import the Client module it may be informative to link it: https://github.com/Automate-Medical/sero/blob/master/src/client/index.ts. I found myself referencing it to help me understand the example.

Phrasing:

• In Step 2:

  We do this by forming a query against PractitionerRole, which is a FHIR Resource that defines specializations.

  Replace "specializations" with "specialties". I rarely see "specialization" used to refer to the area in which a practitioner specializes, and the PractitionerRole resource uses specialty.