Add & Update Developer Docs: GitHub Codespaces Setup for Development and User Research

[bellepx0]

Request type

• Writing new documentation
• Updating previously published documentation
• Reviewing recently written, never-before-published drafts

Number of docs

1

Subject matter expert

AEDP team:
Adam Whitlock @adamwhitlock1 - Engineering Lead
Belle Poopongpanit @bellepx0 - engineer
Lynn Stahl @msbtterswrth - Product Manager

Approvals

No response

Embedded media

• Screenshot(s)
• Diagram(s)
• Video(s)

Audience

• Developers
• Designers and researchers
• Product managers
• Other

Anything else?

Context

The Authenticated Experience Design Patterns team has successfully utilized GitHub Codespaces to spin up an instance of the VA.gov website for our user research sessions. During these sessions, we’ve developed documentation that explains how to use GitHub Codespaces specifically tailored to the needs of our user researchers.

We would like to propose contributing our existing documentation to the Platform’s developer docs, specifically by integrating it with the current GitHub Codespaces documentation. This will provide a unified resource for both developers and non-developers (e.g., UX researchers) on how to effectively use GitHub Codespaces for different purposes.

Below are the steps we are suggesting for the new content addition:

1. Remove “Using GitHub Codespaces” section out of “Frontend developer documentation/ Run and build VA.gov locally”.
2. Put “Using GitHub Codespaces” as its own section.
   Example structure in screenshot below:
   

Example Content:

Overview

This document provides guidance on setting up GitHub Codespaces for both local development and user research environments. It consolidates the instructions and best practices for developers working on the VA.gov website as well as researchers who need to set up testing environments. The following sections will cover both workflows and provide specific instructions for each.

// From the intro in existing docs //
Github Codespaces provide an Integrated Development Environment (IDE) that is accessible entirely in a web browser. It is essentially a web based version of VS Code running on a cloud based virtual machine.
Codespaces is available for all members of the Department of Veterans Affairs organization on Github. Application config for Codespaces is a work in progress.
See #codespaces on Slack for additional questions about using Codespaces.
//

Setting Up Codespaces for Development/

Use content in existing docs on “Using GitHub Codespaces”, starting from “Getting started” up to and including “vets-api in Codespaces"

Setting Up Codespaces for User Research/

Use content in our team docs from “Introduction” up to and including“Best practices"

Resources

1. Codespaces documentation: GitHub Codespaces
2. Codespace Walkthrough Video

Troubleshooting

Use content in our team docs from "Troubleshooting" section

Advanced/

Use content in our team docs from "Bonus-Automatic Public Codespace Creation"