Why the Slow Roll Chicago working group uses GitHub to collaborate

Published on May 25, 2015 by Steven Vance

When the Slow Roll Chicago project in the transportation breakout group began in December at Hack Night, the emails started flying right away.

This was mainly because there was a lot to say at the start, as we needed to agree on the group’s mission and plan.

Problems using email started immediately, though. Not only were there many emails going back and forth among people listed on the TO and CC fields, there were people who weren’t able to take part in these discussions.

That happened because it was difficult to keep track of who had been added to the discussion and who hadn’t, especially when it came to integrating new members of the group.

I wanted to overcome these problems by using a proper collaboration tool.

Email wasn’t just limiting our discussion quality and member inclusion, it was also limiting file storage, file sharing, and file versioning (which file is the latest?). Email has tended to demand a lot of attention, and there’s a lot of wasted time typing responses. I wanted to use a tool that didn’t have such demands, and that helped organize responses into actionable requests and delegation.

Using email made it impossible to see what tasks people were working on, and the progress they were making at any given moment.

Finally, email tends to be private but our work needed to be public so that it could be independently verified but also replicated for use in other locales.

I believe that it’s easier to train people on how to use a new tool well than to retrain on how to use an existing tool – email – better.

GitHub has solved all of these problems for our group while also creating a secure and versioned programming code storage system for the final outcome: a website.

Hack Night being a tech-oriented meetup is a good reason to use and teach this modern tool widely used by people in technology industries. Many of our members are still learning it but they have support from people within our group and from others who attend Hack Night.

GitHub handles our discussions, task assignments, task progress, notes, and files. Here’s how:

When you want to discuss a new idea, like using dynamic images to show what a building could look like under certain conditions, you would make a new “issue”, titled, “Use dynamic images to show the user some building design possibilities”. Use rich text and images in the issue to describe and visualize the idea.

GitHub has granular notifications settings that alert project members to this new “issue” after which they can respond to your idea. After it’s decided that the issue should be resolved in a specific way, you can assign the issue a desired milestone (a future project version) and project members.

One milestone could be “Preview to the management team” which is a previously-discussed status that should happen in a couple weeks. A second milestone could be “Post-launch” – things to finish after launching the product – that’s defined offline.

Each milestone tracks the issues that you’ve associated with it so you can see progress. When the assigned members finish a task, they “resolve” the issue by closing it.

Need documentation? For many coding or GIS projects, a data dictionary may be necessary and GitHub provides each project repository with a wiki in which you would describe how the project is set up, and what certain fields or values mean.

Finally, GitHub can store files – any kind, and as many versions. If you need to update a CSV file of street addresses for the project, just make the edits in your preferred editor on the desktop and then “commit” your changes with a short description of what you changed. Sync this commit back to the repository so that all project members now have access to the file.

This was originally posted on Steven Can Plan in March 2015.

About the author

Steven Vance is a web developer and transportation planner who writes for Streetsblog Chicago.