Skip To Main Content

Bocoup’s Most Important (Empty) GitHub Repo

Posted by Greg Smith

Jan 09 2015

Bocoup loves GitHub. Our code lives there, we collaborate and code review using Pull Requests, and it makes deployment a breeze. For the last year, we’ve even started using GitHub to manage Bocoup.

What?

As Bocoup has grown, we’ve started using new tools to manage information internally. We wanted a company Wiki, but which one to use? A new “Bocoup Meta” repo in GitHub with a Wiki ended up being a good choice. What we didn’t realize yet was that the Issues in that repo were going to become just as important.

Wiki

Why use GitHub’s Wiki? You could spend all day comparing features, but in my experience it doesn’t matter much. We already use GitHub and it’s always easier to adopt tools you already know. Being able to easily link to Issues, Pull Requests, and user names is great too. GitHub it is!

What goes on the Wiki? Some pages are related to HR. For example, having a “Welcome to our company!” page with a list of resources is incredibly useful. New hires are encouraged to add anything they learned that wasn’t already documented.

Our Wiki also has technical and cultural content. One example of a technical page is “The process for setting up a new subdomain.” A cultural page could be a list of places to eat around the Boston office. Incidentally, if you’re ever visiting Bocoup in Boston, you need to eat at Zo.

Issues

That Wiki stuff is pretty typical. Here’s where it gets weird. At first we had the idea to create GitHub Issues for all our projects, both internal and external. As time went on the Issues went beyond that.

Some of our “Meta Issues” are projects that people are working on. However, if a project is ongoing, it probably has its own GitHub repo. What’s more interesting is Issues for potential projects. Sometimes someone will make an Issue for a wild idea and it will get some discussion and brainstorming. Some ideas don’t turn into projects, but it’s great to have that discussion documented in a proper place. Some of the Issues end with a comment that says “I’ve started this! Here is a link to the repo.”

Something we didn’t anticipate is folks using GitHub issues as a discussion board. At first this seemed weird, but in practice it works great. Some Issues will just be updates on what is happening in part of the business. Some are technical conversations like “What kinds projects do you think are good to use Node for?” One nice thing about this is that you can choose which of these to subscribe to. If they were emails they’d all go straight to the inbox. Another advantage is that the Issue list becomes a unified way to see what conversations are happening at the company right now. It even lets new hires get up to speed on what’s going on at the company a lot faster.

None of this is unique. Lots of companies have discussion boards. It’s just neat that we didn’t need a new piece of software to get it. Everybody already knew GitHub.

How does it work?

As a small engineering organization that already uses GitHub, this system works great for us. Still, the system isn’t perfect. For example, the semantics of “closing” a discussion don’t always apply: a discussion that reached no conclusion might instead be considered “archived”. We also have a company mailing list, so there is a subtle overlap between communication channels. Sometimes it’s not clear when to use what.

Are there any other teams out there that do something like this? How is it working for you? How is it different?

Posted by
Greg Smith
on January 9th, 2015

Comments

We moved off of Disqus for data privacy and consent concerns, and are currently searching for a new commenting tool.

Contact Us

We'd love to hear from you. Get in touch!