Starting a CDS Hooks API guide

[mseckykoebel]

@jdjkelly @jamais-vu right now the v1 of the API guide is done excluding the final section.

The guide starts here: https://docs.sero.run/overview/guides/cds-hooks/getting-started-todo, and goes through to the final section marked todo.

Because the guide is pretty long and through there might be some continuity errors/narrative errors that I might have missed. I appreciate any feedback on making this better!

[jdjkelly]

@jamais-vu I'll let you take first read through.

Let's correct any typos in-line (just do it live) and keep everything else here. Beyond that, let's think about these things while reviewing:

• Does it make sense to read, are there any narrative problems
• Check any code examples, make sure you can reproduce

[jamais-vu]

Overall I think it holds up narratively. Each section naturally builds on the previous section. A reader with little prior knowledge could come away having learned enough to know where to start.

I especially liked that you offer the reader the option to start in any of the more advanced sections by cloning the starter code up to that point. I'm a big fan of documentation that lets readers choose the level of depth they want and get up to speed as fast as possible. It also means someone who already knows the basic parts can skip to the advanced parts.

The setup guides for the CDS Hooks sandbox and Logica sandbox were clear and concise, I had no problems following them to the letter.

The only section I think could use more detail is What Is CDS Hooks?. If had never encountered CDS Hooks before, I would need to refer to the spec to know what I'm dealing with. Maybe the definition of "CDS" should go before the definition of "CDS Hook", since knowing what a CDS Hook is depends on knowing what CDS is. Might also be informative to include a diagram of a CDS Hook trigger (eg https://cds-hooks.org/images/overview.png).

There were also some phrasing issues scattered throughout, which I'll add as comments to Gitbook since that will make them easier to reference. I tried to be thorough so feel free to disregard ones which seem more like nitpicking than improvements/clarifications.

I noticed two issues with the code examples:

• The examples for the CDS services don't include how to add them to index.js, so just copying and pasting the code won't run. I was able to get them running without much trouble, but someone unfamiliar might get stuck here. (Though /cds-hook-api-guide in the Sero repo does have the correct index.js so this may be less of an issue when the reader can clone starter code.)

• In the Prefetch and Context Service Handler section, the code excerpts for handler could be confusing. It may not be immediately obvious to a reader that the return statement goes inside handler, because the handler definition and the return statement are broken up between two code blocks, both of which have the same indentation level.

Aside from those two points, the code examples were explanatory and ran without problem.

(The final section Links, Suggestions, FHIR Queries is still marked "todo" and doesn't look complete so I'll hold off on feedback for that, unless you want me to review it as-is.)

In general I liked it and think it's a helpful guide. It's nice to have this information in one place!

[mseckykoebel]

Yeah, the third section is en route. I had to get the code done for that example before working a lot on the documentation because of how variable the code was. I'll go through and make some edits based on these suggestions.

Thanks so much for giving it a read!

[jdjkelly]

I did a careful read through of the first sections (up until the setup page). I also took @jamais-vu's feedback above into consideration. I then made and merged an edit with the following:

1. I consolidated the content on Getting Started and What is CDS Hooks into a single page at the top level/root of the guide: https://docs.sero.run/overview/guides/cds-hooks I think this makes it narratively stronger by putting everything you really need to know ahead of time in one place at the start. I think it also makes the rest of the guide as a whole feel less daunting in terms of the number of pages/steps.

2. I added "content flourishes" like for example the header link to How to build in health the easy way, the link to Decision Support

3. Shortened the content in Getting started section to be tighter/succinct

4. Borrowed a bunch of content from the CDS Hooks section of the Decision Support page, including bringing over the diagram

5. I did a couple of other consistency changes like a) capitalizing CDS Hooks/Service/Client etc, b) using "we" instead of "you"

I'll do more of this tomorrow, and more critically I'll read through the actual code sections.

[mseckykoebel]

Amazing, thanks! I was unsure of whether to use 'we' or 'you' and ended up going all-in on you. I'll give it another read-through and make some final edits considering these fixes/suggestions.

It will also help me write example 3 today and tomorrow. I will let you both know when it is done and live!

[jdjkelly]

Setup

Merged

• Condensed the bash and powershell commands into a tabbed section (you can add tabs for alternates)
• Added filenames
• Expanded/reworked config options section
• Changed some titles

Feedback

Nothing else, this is good

Creating our first service

Merged

• Added filenames
• "CDS Hooks Sandbox" is the preferred title for it, I tried to find all of the references on the page and switch them
• Added some more context about what the CDS Hooks sandbox is
• Replaced the screenshots with "float-y OS X" ones - MacOS just makes better looking screenshots
• Think I did a bunch more service -> Service, client -> Client, hook -> Hook edits
• Added a optional pull from the source notice at the top
• Changed the URL of the page to match the title

Feedback

Agree with @jamais-vu re:

The examples for the CDS services don't include how to add them to index.js, so just copying and pasting the code won't run. I was able to get them running without much trouble, but someone unfamiliar might get stuck here. (Though /cds-hook-api-guide in the Sero repo does have the correct index.js so this may be less of an issue when the reader can clone starter code.)

for this, @mseckykoebel can you add a step at the end of the build section of this first guide that just shows what index.js should look like and then telling them to run node index.js

[mseckykoebel]

Just added! Sorry for forgetting to add the step for index.js and the edits for package.json, blanked on that one. index.js is also modified slightly in the 2nd and 3rd examples so I will add that in as well.

[mseckykoebel]

I just finished updating the documentation to match #77, or the enhancements to the API guide pre-connectathon. Can be found here.