Redesign New VFS Team Member gh template

[shiragoodman]

User Story

As a Governance team member, I want to redesign the New VFS Team Member gh template to include only the administrative tasks so that the ticket is simpler for VFS teams to complete and easier for Platform to take action.

Assignee: @allison0034
Peer Reviewer: @erinrwhite

Description

In the last few tickets, Governance has been working to separate the educational tasks associated with Platform Orientation from the administrative tasks. This is so that we can only keep the administrative tasks within the GH template because these are the only tasks Platform actually validates for completion. Platform has our own tasks associated with Platform Orientation, seen under the Platform Checklist section of the current New VFS Team Member gh template, and several of the VFS administrative tasks are prerequisites for the Platform tasks. The educational tasks will soon be moved to live on Platform Website.

The purpose of this ticket is to redesign the New VFS Team Member gh template to limit it only to the administrative tasks for the VFS team member to complete, as well as the Platform Checklist items that Platform will complete. The redesign should also include a link to the educational tasks on Platform Website (this will have to be a placeholder as this page does not yet exist), and the instructions at the top of the current template should be streamlined.

In December 2022, Governance completed some user research on the Platform Orientation process and the research findings may still be valuable for reference when redesigning the template.

Lastly, it is recommended that the redesign of the New VFS Team Member template be completed in Confluence, and a pull request is NOT created. This is because it still may be sometime before the template is published, and we don't want the pull request to be accidentally merged before it's ready. Do NOT publish any changes to the New VFS Team Member template as part of the scope of this ticket.

Impacted Artifacts

Live pages

• New VFS Team Member gh template

Drafted pages

• YAML file
• GH PR file.

Tasks

• Using the administrative tasks identified in ticket Separate the tasks into educational or administrative #94446, create a new draft of the New VFS Team Member template in Confluence
• Ensure the Platform Checklist items remain in the template.
• Ensure we have included a link to the (placeholder) page on Platform Website/Getting Started/Platform Orientation for VFS teams to review the educational tasks
• Try putting yourself in the shoes of a new VFS person. This is the ticket you're told to complete. Does it make sense to you? Is there anything confusing about it? Is there information (in the current state) that you gloss over? How can we make the content instructional without overloading the new team member with too much content? Is it clear who completes which section? Should we consider converting this template into a YAML template?
  • Side note: if we do think a YAML template would be a better user experience for the VFS team member than the current markdown template, you may want to create a test version in your own repo on gh. Please check in with Shira if you are unsure or have questions how to proceed.
• Share your new template design for peer review and feedback

Peer Review

To be completed by peer reviewer

• User story and acceptance criteria are met

Acceptance Criteria

• We have redesigned the new VFS team member template to no longer include any educational tasks for the VFS team member to complete.
• We have redesigned the New VFS team member template so that it still includes the Platform Checklist items
• We have redesigned the New VFS team member template so that it includes a reference to the educational tasks on Platform Website (note: page does not yet exist so please create as placeholder)
• We have redesigned the New VFS team member template so that the instructions for completing the template are clear, concise and easy to understand and follow

Team Notification

• Slack post on #platform-governance-team
• Presentation at Weekly Initiative Meeting
• No notification needed

How to prepare this issue

Refinement

• Ticket has user story, description, tasks, and acceptance criteria
• Ticket has been sized
• Once all above items are checked, add the 'Ready' label.

Planning

If this ticket is picked up from the Backlog mid-sprint, connect with Shira to ensure the below items are completed correctly

• Ticket has been discussed as a team at Planning
• Ticket has been assigned to appropriate initiative or quarterly epic
• Ticket has been assigned to a Sprint
• Ticket has been moved to the Planned pipeline in the Governance team board
• Ticket as an assignee and peer reviewer

[allison0034]

Created PR

[shiragoodman]

@allison0034 are you going to be converting this to a YAML template? Have we considered that? I imagine there's some pros and cons to it. LMK what you think.

[allison0034]

@shiragoodman I am not sure yet, I wanted to see what this would look like once restructured.

[shiragoodman]

@allison0034 since the template has both VFS actions, and then Platform actions, we'd like to have both there without manually adding anything after the ticket is submitted. IIRC, YAML does not allow for the Platform actions show up after the ticket is submitted... they must be present from the start which I'm not sure will work out too well with VFS teams. I'd imagine they would attempt to complete that section. @briandeconinck does that sound right to you?

I'm wondering if it might make sense to pull Platform Support team in now, since they're the team from Platform who will be interacting with this template, and see what their preference is.

[allison0034]

@shiragoodman I just spoke with Brian and I don't think YAML will be a good fit for this. The only benefit would be adding text boxes to the things like "name" but once they submit, they will lose all static text and will not be able to edit unless they look at the markdown file.

[erinrwhite]

Reviewed the PR #96178 and left some comments 👍🏻

[allison0034]

Chatted with Shira, educational tasks need to be removed. After removing those, I believe this would be a good candidate for YAML... so now I am YAMLING!

[shiragoodman]

Thank you @allison0034 ! I also think that the Platform Support team should take a look at this when we're done so they can provide their input, since they're the team that will be handling these tickets for Platform. I think the best approach would be to handle that in a separate ticket for the next sprint. I will write it up. Please lmk if you have any questions!

[allison0034]

This will move into the next sprint, first time working with YAML so I had a bit of a learning curve. I have a test template up, need to see if I can add the 2 platform tasks after it is submitted.

[allison0034]

@shiragoodman I know Erin is out, if you have time do you want to take a peek at this template?

[shiragoodman]

I took a quick peek. I might have more feedback later, but my big concern now is that we make it VERY clear that the VFS team member is not supposed to complete any items on the Platform Checklist. Maybe we can use a line divide? Or make the Platform Checklist section a higher level heading?

---

Also "Tasks for offboarding teammates" is a VFS task, not Platform. We may want to rework the language for that one too. It's supposed to just be informational so that if/when someone on their team leaves, they're aware of the steps they need to take. Maybe it belongs in educational tasks? up for discussion.

[allison0034]

@shiragoodman I added some horizontal rules to help break up the sections.

Quick question, off boarding would happen after this ticket was submitted and a team member would have been here for awhile (ideally) correct? For example, Allison starts in October of 2020, completed her tasks in this ticket, clicks create. Then platform completes the tasks in platform. Years later Allison hits the lottery and resigns... VFS opens Allison's ticket and completes the off boarding task.

Is that the correct flow for off boarding : )

[allison0034]

@erinrwhite if you want to review you can, it may change slightly.

[shiragoodman]

@allison0034 can you elaborate what you mean when you say, "VFS open's Allison's ticket and completes the off boarding task" ? VFS team (either Allison or someone on behalf of Allison) would open the Offboarding ticket if/when Allison leaves.

The task related to offboarding in the New VFS Team Member ticket is to inform individuals of the offboarding process, not to execute the offboarding process. The goal of that task is to share information with the VFS so that in the future, if/when they or someone else from their team departs, they're familiar with the process and what's required of them.

[allison0034]

I aligned with Shira via Zoom. @KKitagawa-Bosch please include the off boarding task in your educational page.

[allison0034]

@erinrwhite please review the YAML file and GH PR file.

[erinrwhite]

@allison0034 The YAML looks good! Couple of things

YAML file name and ticket title Both have extra 2's in them - should be removed from the ticket metadata

Link update: Getting help from the Platform in Slack link is broken, should go to https://depo-platform-documentation.scrollhelp.site/support/getting-help-from-the-platform-in-slack

Formatting for "Tasks for..." headings - is there a way to make these sub-headings (Tasks for everyone, Tasks for Front-end and Back-end Engineers, etc) h2's or h3's rather than labels? That's more semantically correct here, I think.

**Implementation note: ** It looks like, when we are ready to go live, we will need to remove the orientation-epic.md file entirely and replace it with a new new-vfs-team-member.yml file using the code that you used in your personal repo. Then we would need to update the link in the guidance for new team members page on platform website to link to the new issue template URL. That work is not part of this ticket, though - just a note for the future.

[allison0034]

@erinrwhite

YAML file name and ticket title Both have extra 2's in them - should be removed from the ticket metadata

Yes! That is because I have more than 1 file, it is not ready to be published, but yes this would be removed.

Link update...

Fixed!

Formatting for "Tasks for..." headings...

There is not, these are labels on the checkboxes. We could add headings but then what would I name the checkbox labels? Any ideas?

**Implementation note: **...

@shiragoodman do we have a ticket for publishing this yet so I can add this note?

[shiragoodman]

@allison0034 yes, just add as a comment to this ticket: #94452 It still needs refinement, but a comment should suffice for now.

[erinrwhite]

@allison0034

these are labels on the checkboxes. We could add headings but then what would I name the checkbox labels? Any ideas?

Dah! You're right - I was misunderstanding how this worked. All good.

Two more things I saw:

(1) we need to make sure to add the labels to the new YAML template

labels: ["platform-orientation", "new-vfs-team-member", "platform-tech-team-support"]

(2) for the educational tasks, do we want to have it as a checklist item (implying that they should finish those tasks before submitting the ticket) or should we have it as a separate section on the form "After you submit this ticket"?

[allison0034]

@erinrwhite yes on the labels! I will add that to the implementation ticket, we are not publishing this yet and I did not want to submit any tickets with those labels right now since we are testing.

I don't think we want them to do the educational tasks after they submit this ticket. I am not even sure if those are going to be check boxes. Since we do not know exactly what that page looks like we will reevaluate once it is complete.

[erinrwhite]

Sounds good to me. Review complete and boxes checked! Thanks for the back n forth.

[shiragoodman]

@allison0034 In the YAML template, I see the language, "Complete the form and tasks then click create." However there is no "create" button. The button is called "Submit new issue"

This content is also a little funky: "Welcome to the Department of Veterans Affairs (VA) Veteran Facing Services (VFS) team." It makes it sound like they're on a new team called VFS, but that's not accurate. They're on a team that is classified as a VFS. Can we rework the language a bit so it's more clear? Let me know if you have questions about this.

I think this language may also be confusing:
"Note: this ticket should not be submitted/created until after you receive access to the appropriate repos."
That's not exactly true. I would reach out to Alyssa for her teams input here. Or possibly Andrea if Alyssa can't help. The VFS team member isn't waiting on receiving access to the appropriate repos (that is the step Platform Support completes when the ticket is submitted), but rather they're waiting until they've been adjudicated and fingerprinted by VA. I'm not sure what appropriate language to use, but "appropriate repos" is NOT CORRECT.

[shiragoodman]

same comments for the MD file too - thank you!

[allison0034]

@shiragoodman I updated the verbiage for the button in the YAML file, in the MD file it is "Create".

Honestly, do we even need a "welcome" message? They get to this form from a web page that explains things. I removed it. Let me know what you think.

I will reach out to Alyssa about the note.

[allison0034]

@shiragoodman @erinrwhite am I good to close?

[shiragoodman]

@allison0034 yes, fine by me.

[erinrwhite]

@allison0034 all set.