Migrate API Programmer's Guide to Web Content

[BerniXiongA6]

Problem statement

As a ReportStream user, I want self-guided instructions to learn how submitting data reporting via API works.

As the ReportStream team, we need to update the content so that it matches the API functionality and we can provide accurate and helpful information to support API end users. And this content would best serve the users as an interactive document on the website.

What you need to know

• Current state: API programmer's guide is currently drafted as a Word doc, converted to PDF, and shared as a link on the ReportStream website
• Future state: API programmer's guide content will be populated as web copy on its own static page on ReportStream.cdc.gov
• OLD: See Mural board for info on the IA (to see where the programmer's guide could be located)

---

NEW from Design and Content team:

• Design: Full prototype (design + wireframes, annotated)
• Design: Style guide for new components & type styles
• Content: Copy doc table format with design components noted

• Content: Traditional doc format More information can be found in #8342

Scope

This is the first pass at getting the API Programmers Guide into web format. The scope of this epic is:

• Implement the design as seen in the Figma Final Design/Wireframes
• Implement Content per Programmer's Guide Content
• Regarding typography,
  • no need to change any type styles that we have on the site right now to match the Figma file
  • will need to add new "H4" and "Body, Small" type styles
• For all tables, use simplest table style possible for now (no need for sorting, etc). The Custom Table Component work that is going on in parallel will come back and enhance these tables in the future. So just make them bare-minimum useable for now.
• HL7 Field Requirements will be downloadable as .xls only

Follow-on feature epic: #8384

Next Steps

• [x] Engr creates tickets for API Programmers Guide
• [x] Align on tickets and timeline between Joseph, Stephen, Andrey, and Chris
• [ ] Engineering Build
• [ ] Track Success

How to Measure Success

Primary:

• Visitors to the API Programmers Guide webpage over the next month as a percentage of total visitors to the website

Secondary:

• Ad-hoc feedback from users
• Reduction of support tickets

[HeatherRienks]

Per sync on 11/30/22, we will prioritize this! Will create new tickets as part of this epic for next steps - possibly add Error Codes as first section to update on site?

[hannasage]

@fmccaf1 @drew-usds @HeatherRienks I updated the AC for this on November 30th with what this, overall, is meant to accomplish. I did not know whether there was more AC from a design/product pov that isn't outlined here. Worth reviewing and updating!

[BerniXiongA6]

Hey Exp. team, just an FYI that O&O will be adding our individual tickets to this epic every time we have a Version update for Programmer's Guide as well as any other work that is relevant to the guide. That way both scrum teams can more closely align on the work we're each doing sprint to sprint. Any questions, please let us know. Thx! @HeatherRienks @brandonnava @brick-green @kevinhaube @fmccaf1 @lizzieamanning @chris-kuryak

[BerniXiongA6]

Hey all, just a quick note here to update everyone that @chris-kuryak @fmccaf1 and I agreed that I'll remove O&O tickets from this Epic. We'll house our programmer guide tickets underneath an O&O specific epic. Thanks for the awesome work x-collabing on this!

[chris-kuryak]

Separating this epic out as just the research phase of the larger project to move the API guide into web-based content.

[stephenkao]

@audreykwr @jpandersen87 Regarding the page slugs, does the following sound good to you in terms of slugs and anchors? (just using the convention of lowercased and hyphenated page/section titles)

ReportStream API page

• /resources/reportstream-api
• /resources/reportstream-api#onboarding-overview
• /resources/reportstream-api#about-our-api

Getting started page

• /resources/getting-started
• /resources/getting-started#format-and-validate-a-fake-data-file
• /resources/getting-started#set-up-authentication-and-test-your-api-connection
• /resources/getting-started#test-real-data-in-production
• /resources/getting-started#start-sending-data-in-production

Documentation pages

• /resources/documentation
• /resources/documentation/data-model
• /resources/documentation/data-model#common-errors
• /resources/documentation/data-model#legend
• /resources/documentation/data-model#patient-data-elements
• /resources/documentation/data-model#order-and-result-data-elements
• /resources/documentation/data-model#specimen-data-elements
• /resources/documentation/data-model#ordering-provider-data-elements
• /resources/documentation/data-model#testing-facility-data-elements
• /resources/documentation/data-model#ask-on-entry
• /resources/documentation/data-model#reporting-and-ordering-facility-elements
• /resources/documentation/responses-from-reportstream
• /resources/documentation/responses-from-reportstream#errors-and-warnings
• /resources/documentation/responses-from-reportstream#response-messages
• /resources/documentation/responses-from-reportstream#json-error-responses
• /resources/documentation/sample-payloads-and-output
• /resources/documentation/sample-payloads-and-output#sample-csv-payload-and-output
• /resources/documentation/sample-payloads-and-output#sample-hl7-v2.5.1-payload-and-output
• /resources/documentation/sample-payloads-and-output#example-data-models

[audreykwr]

@stephenkao looks great to me. there are ways we can make some of them simpler (e.g. removing repetitive data element titles) but unless you see a reason why that'd be helpful this is fine.

[stephenkao]

@audreykwr I don't think it really matters. There's some value in being verbatim just in case we want to automate the creation of the hash links (like just "sluggify" the section titles verbatim), but at this point I don't think it really matters!

[kewitham]

test comment

[chris-kuryak]

@kewitham thanks

[chris-kuryak]

Feature released! Closing.