Stakeholder engagement: which API documentation UI to use?

[shmonks]

Overview

We need to get feedback from stakeholders about preferred form of API documentation, following Fang's research indicating pros and cons of two main options: Swagger and Redoc

Action Items

• Create draft of slide deck
• Review
• Send link to Bonnie for feedback
• Send message to VRMS (and CTJ?) PMs, asking if we can join one of their team meetings to talk about it, with link to version of slide deck saved to local drive
• Record stakeholder feedback in a comment below

Resources/Instructions

• Add OpenAPI (swagger) docs to our documentation #239
• Swagger UI vs. Redoc #381
• People Depot Team Meeting Agenda 2024 #103 (comment)
• Completed slide deck: https://docs.google.com/presentation/d/1ugoZ33ptZTdiAjDZpd5bd7FrLQbIVcOPVjP4GkJ0EiE/edit#slide=id.g1443c52839c_0_2

[shmonks]

Hi @vanessaavviles - please consider the following questions and add an update below:

1. Progress: "What is the current status of your project? What have you completed and what is left to do?"
2. Blockers: "Difficulties or errors encountered."
3. Availability: "How much time will you have this week to work on this issue?"
4. ETA: "When do you expect this issue to be completed?"
5. Pictures (if necessary): "Add any pictures that will help illustrate what you are working on."

[vanessaavviles]

Fang could not make the meeting this past tuesday, so we will work on going through the presentation all 3 of us next tuesday's meeting and have it ready to show the team thursday of next week.

[vanessaavviles]

Finished presentation, Fang and I decided it would be best for the 3 of us to look it over together for one last glance before presenting it at all teams.

[shmonks]

Please provide update

1. Progress: "What is the current status of your project? What have you completed and what is left to do?" We met this morning and ran through final changes and cleanup, which Vanessa will implement before finalization
2. Blockers: "Difficulties or errors encountered."
3. Availability: "How much time will you have this week to work on this issue?"
4. ETA: "When do you expect this issue to be completed?" Next week
5. Pictures or links* (if necessary): "Add any pictures or links that will help illustrate what you are working on."

• remember to add links to the top of the issue if they are going to be needed again.

[vanessaavviles]

Revised PP with sarah and fang, need to make a few changes to the presentation before revising again. After that, PP should be ready to demonstrate to team.

[shmonks]

Please provide update

1. Progress: "What is the current status of your project? What have you completed and what is left to do?" Slide deck completed and ready for review: https://docs.google.com/presentation/d/1ugoZ33ptZTdiAjDZpd5bd7FrLQbIVcOPVjP4GkJ0EiE/edit#slide=id.g1443c52839c_0_2
2. Blockers: "Difficulties or errors encountered."
3. Availability: "How much time will you have this week to work on this issue?"
4. ETA: "When do you expect this issue to be completed?"
5. Pictures or links* (if necessary): "Add any pictures or links that will help illustrate what you are working on."

• remember to add links to the top of the issue if they are going to be needed again.

[ExperimentsInHonesty]

This was presented in the people depot team meeting tonight.

• Ethan looked at it and said whatever Fang recommends is fine

• Bonnie looked at it and said redocs is her recommendation

• Fang recommends redocs

• Ask the CTJ and VRMS tech leads for their recommendation after seeing the presentation

[shmonks]

Remember to update the following issues with feedback once we have it:

• PD: VRMS Stakeholder Meeting Agenda and Notes #377
• PD: CTJ Stakeholder Meeting Agenda and Notes #426

[shmonks]

Stakeholder feedback:

• Website team and CTJ prefer Redoc
• VRMS prefer Swagger

I.e., Redoc wins