Building a Git training workshop for The Good Docs Project
Created a hands-on Git training program that onboarded 10-15 new contributors to The Good Docs Project, enabling them to make their first contributions independently.
Overview
Designed and delivered a 3-hour Git workshop for The Good Docs Project, addressing a bottleneck where new contributors wanted to participate but lacked Git skills. Built a sandbox website to provide a low-stakes practice environment for learning.
Problem
The Good Docs Project experienced an influx of new contributors following Write the Docs 2022, but many did not have Git and GitHub experience. Template working group leads spent significant time teaching Git one-on-one. We needed a better way to onboard contributors without overwhelming the team.
Approach
I collaborated with Alyssa Rock to design a 3-hour workshop covering the Git basics: add, commit, push, pull. Then I built a sandbox site using Hugo and Netlify for the workshop. Students cloned the repo, made changes to the content, and merged their pull requests. This mimicked the real Git and GitLab workflow they'd use in open-source projects.
Challenges
- Navigating Git setup issues for multiple operating systems
- Teaching the essentials without overwhelming contirbutors
Key Tasks
Prioritize a hands-on 3-hour workshop instead of asynchronous learning
Contributors needed hands-on help with setting up their Git environment and understanding the Git workflow. Creating a hands-on workshop meant that we could answer questions immediately and troubleshoot any blockers as a group.
- Video tutorials (students wouldn't get help when stuck)
- One-on-one mentoring (wouldn't scale as we only have two instructors)
Build a sandbox website instead of using the project website
The tech team didn't want high volume of PRs on the project's website. A sandbox site provided a safe environment for students to practice the full Git workflow.
Focus on Git essentials: add, commit, push, pull
New contributors only needed these commands to make their first contribution to the project. Teaching merge conflicts or advanced workflows would have overwhelmed them.
Frame the workshop around a real-world scenario
Rather than have the students practice Git commands, I created a scenario for the workshop. A fictional business called The Good Dogs Project needed editors to fix Markdown errors in their blog posts. This framing turned abstract Git tasks into a realistic documentation project. Students understood why they were doing each step, which improved engagement and helped the concepts stick.
Tech Stack
- Hugo
- Astro
- Markdown
- GitLab/GitHub
- Netlify
Impact
- 10-15 new contributors successfully completed the workshopContributors trained
- 100% of graduates felt confident enough to work independently on template projectsIncreased student confidence
- Training materials adopted by other organizationsReuse beyond TGDP
The workshop became a successful onboarding solution. Instead of working group leads spending hours teaching Git individually, we had a structured, repeatable 3-hour workshop. All graduates successfully made their first contributions and continued contributing to template projects. Additionally, Alyssa taught this workshop several times at another open-source project.
Learnings
- Hands-on learning is essential for teaching technical skills
- Sandbox environments lower barriers to learning
- Real-world framing makes abstract concepts concrete and memorable
Notes
This project was personally meaningful because I got to use my curriculum design skills from teaching again, like creating learning objectives and scenarios for assginments.
Building The Good Dogs Project website was a fun challenge, too. I created the Hugo site using a template created by Bryan Klein, a Tech Team member at TGDP. Some community members contributed blog posts for the training, and I introduced intentional Markdown errors. Recently, I redesigned the website using Astro.
Using a working website helped the training feel real for our students. They solved problems that they would likely encounter on another open-source project or on the job. As an instructor, I enjoyed celebrating our students’ first merged pull requests.
The training is still in use today, and Alyssa and I will likely run it during our next release cycle. The website is hosted on Netlify if you’d like to view it.