Documentation Updates

[karlnaden]

Summary

Update documentation and test descriptions based on feedback from ONC, including

• splitting out suite descriptions into separate markdown files that can be linked to from test descriptions and other documentation
• add additional description to user input validation tests
• clarify the meaning of the server "status check" tests -> now claim response decision validation, and move them into the submit group rather than their own group. Also made them skip and optional until actually implemented.
• Separate out the stub notification test.

Testing Guidance

• note that some links point explicitly to a file that doesn't yet exist in the main brach, so you will need to add the branch name to the url (after /tree/ -> /tree/suite_description_breakouts/) for the link to work from descriptions in the running test kit.

[karlnaden]

One remaining question. Scott had a suggestion to update the description of the $submit and $inquiry operations. My note indicates "expand description of operations -> both described in the IG as "submit a claim for..."". I think our descriptions seem pretty good, at least in the client tests:

• submit: submits a claim using the $submit operation
• inquiry: inquires about a pended claim using the $inquire operation

so I took the approach of updating the server to follow those names. Does this sound right @arscan - did you think there was something different that Scott wanted here?

[arscan]

This absolute link doesn't work. The link in the suite description in the running version on inferno.healthit.gov is currently broken as well. I think you need to remove the blob segment?

[karlnaden]

https://github.com/inferno-framework/davinci-pas-test-kit/blob/main/config/PAS%20Test%20Kit%20Client%20Test%20Demo.postman_collection.json is the link when I navigate to the file, so using that.

[arscan]

so I took the approach of updating the server to follow those names. Does this sound right @arscan - did you think there was something different that Scott wanted here?

I think this is ok. The issue is that we tend to want to use very precise language from the spec so everyone knows what we are formally testing. The formal language here is... well... not great... because "submit" is used to mean 2 different things in the 2 operations. So either we update this to use not-great language that clearly maps to the operation names/titles, or we change the language on our side to 'make more sense'. Maybe we can open a ticket for them to not use 'submit' in the $inquire operation definition? Or something like that?

[karlnaden]

so I took the approach of updating the server to follow those names. Does this sound right @arscan - did you think there was something different that Scott wanted here?

I think this is ok. The issue is that we tend to want to use very precise language from the spec so everyone knows what we are formally testing. The formal language here is... well... not great... because "submit" is used to mean 2 different things in the 2 operations. So either we update this to use not-great language that clearly maps to the operation names/titles, or we change the language on our side to 'make more sense'. Maybe we can open a ticket for them to not use 'submit' in the $inquire operation definition? Or something like that?

Good idea. Submitted FHIR-45391. Also created FHIR-45393 around the inquire vs inquiry issue, which has been bothering me.

[arscan]

Good idea. Submitted FHIR-45391. Also created FHIR-45393 around the inquire vs inquiry issue, which has been bothering me.

I think having it be more active in its phrasing with the primary verb being up-front would be clearest.... "Inquire about the status of a submitted claim" or something. But coming up with concise and clear language here is very hard (I sympathize with IG devs!)

[karlnaden]

But coming up with concise and clear language here is very hard (I sympathize with IG devs!)

I do too!