Streamlining Repos and Creating Organizational Processes
A big reason Systers was looking for a documentation intern, was to work on streamlining their Github repos and creating organizational processes. Systers has participated in Google Summer of Code since 2009! They participate in Google Code In. 2017 brought on Outreachy and 2018 ushers in Rails Girls Summer of Code. On top of that, there are all of the wonderful folks who drop by the organization when they’ve got some downtime from their professional coding gig.
That is a lot of traffic from a very diverse group of people from EVERY level of experience (GCI is ages 13–17, only) from around the globe. Some of these contributors are Open Source pros and some need a hand creating a Github account.
I spent some time at the beginning just working my way through the 14 active repos and ensuring that they all had the basics, things like licenses, a Code of Conduct, and Issue Templates. Then I did things that made my order loving heart skip a beat, like making sure every repo had the same issue labels and that they were color coded using the Anita B.org color palette.
The next big task was putting together contributing guidelines. I spent a little time wandering around Github looking through a few organizations’ guidelines and put something together. It was approved by my mentor and I started the process of adding it to each repo. Another mentor saw the guidelines and brought up some issues.
I had too much information in the guidelines. Even though I’d broken it up into digestible chunks and added links at the top to jump to each section, it was still too much. No one was going to read to the bottom.
I was trying to create a single document that would cover the full range of experience levels that Systers’ contributors possess and it didn’t work.
She pointed out that in my attempts to be inclusive and consistent across the repos, I’d left out any information on how to contribute to each specific repo! I started again. This time I specifically looked at organizations that have huge numbers of repos. Many of them had very simplistic guidelines on Github, then they included links to their websites with further information.
I sat down and wrote out all of the sections I was trying to include in the Contributing Guidelines, the repo wiki, and the ReadMe files. The only parts I want included on Github are generalized information that won’t change often. Changing information to each repo is a test in tedium. You have to add the same information to every repo individually. It’s terrible.
Instead, I’m taking any information that will eventually change, like a newcomer’s starter guide, our Slack channel invite (controversial take: Slack will not last forever), and available internships, and moving them over to the Systers website. I’m going to add links to the website to the appropriate pages in Github.
Now, if someone creates an awesome new tutorial that we want to share with the world, it can be added to the website and not to each, individual repo.
Really I’m just doing all of this because I’m lazy and don’t want to work that hard. Shh…
