Spring 2016, I worked on a 16-person (!) team developing a web app called Gig Central. This app is a website that connects employers with prospective employees, particular students finishing up training programs.
Sixteen people is an awful lot, and though we utilized some agile techniques, a big logjam soon became GitHub. People knew how to use Git well enough, but it didn’t take long before our repo got corrupted due to numerous team members’ discomfort and inexperience with using the Git remote. I include myself in this group; I had never before worked with a team of more than three people to do version control with GitHub. People’s work, my own included, was being committed over and we were losing things. It even required a completely new repo at one point.
So, I set aside my coding contributions to the project and decided I would write the best possible documentation to get all members of our team on the same page with GitHub.
I took some time and wrote instructions for committing and pushing from the command line, and then I wrote a workflow for our team to follow when working on the project. These were both as short and as lightweight as I could possibly make them, with formatting that allowed for easy copying and pasting. GitHub can do an awful lot, but for our purposes we needed just a small number of commands.
Finally I wrote standards and rules for GitHub for the Gig Central project. This was important as well, an added layer of accountability for out GitHub users.
And you know what? It worked. I was surprised and pleased to see our GitHub problems evaporate almost instantly after I published the documents and notified people. The project had enough docs involved already to make people tune out when going over them, but this particular piece was badly needed and people really appreciated it.
Bonus: it made me way better at GitHub myself. And now I have a reference to come back to. Which I do, regularly.
Double bonus: I’ve now embraced Google Doc Templates. They rule.
Now, here’s a cool graphic that I found more helpful than most for understanding GitHub flow:
