How to get government employees to use GitHub

If you missed it, here’s a post on why government employees should try GitHub.

We had five days to get 860 pages of the City of Boston’s budget books onto a website. We’d been working for months and had automated over 90% of the content. Even so, our expert budget analysts still needed to review nearly 100 really important, manually-created web pages right before the scheduled launch date.

No one in Boston’s Office of Budget Management knew how to use GitHub (where we hosted our code), and we didn’t have time to sit with everyone individually while they caught errors and we fixed them.

So we taught them how to use GitHub. The Boston budget govvies learned about commits, they edited and pushed real code — even when I wasn’t around — and they felt empowered to make website changes by themselves in the future. How did we make that happen? Read on…

Credit: Boston’s Office of Budget Management all-stars for their contributions

1. Have an immediate need to learn GitHub.

We had two ways for folks to edit the website: directly on GitHub or by XXXXwithholding baked goods fromXXXX politely tapping our software developer or me on the shoulder and waiting for us to make the changes. Under time pressure, the choice for staff was straightforward, and they were motivated to learn. No time pressure and no immediate need? Then it’s probably not going to happen. It ended up being a small investment of time (~15 minutes per person x 4 people) for a big return on that investment (900+ lines of code changed and an accurate website).

2. Create low barriers to entry

My bets on why most people don’t learn how to use GitHub:

  • What’s a git? (it’s actually #4 on that list)
  • I don’t code.
  • No one will help me if I’m stuck.
  • I’ll mess something up.

Most blockers (as with all new things) had to do with fear of messing up and a lack of confidence that they could do it. For the record, the Boston budget govvies are supremely capable humans. Nearly everyone on Earth (I assume) has felt a lack of self-confidence at some point. Empathizing with that feeling and being patient with folks is the best way to move past it.

How we addressed those blockers:

  • What’s a git? For our purposes, learning version control was absolutely unimportant. I let the budget govvies know what it is, (see “I’ll mess something up”, below) but emphasized that it would be a waste of our time to dive into it at that moment. [Remember, we’re under time pressure!]
  • I don’t code. For the sticklers out there, budget govvies didn’t program, but they did code. They’d heard of HTML, and I told them that markdown, which is mostly what we used to build the webpages, was an easier form of HTML. That explanation (plus smiles and encouragement) was enough to make them feel like markdown was something they could learn.
  • No one will help me if I’m stuck. Ironically, if you rush through the onboarding process, it will take longer. Sit with someone one-on-one as they get signed up for GitHub. Be patient as you go through the screens. Keep them company as they make their first commit. Be patient as they ask you questions. Really. It seriously just took 15 minutes per person, but by leaving plenty of buffer after the teaching session, we didn’t feel rushed to finish… and accordingly finished on time.
  • I’ll mess something up. They probably will mess something minor up, but that’s ok because … version control. Be sure to share your supreme confidence that most users, especially beginners, cannot irreparably mess something up. The version control part isn’t important as long as you communicate your absolute certainty that they can’t mess anything up.

P.S. Make a point to be available to help someone at a moment’s notice. This is where their fear of being permanently stuck can be validated or disproved. Make their first experience with GitHub a positive one.

You might be thinking, “Walking them through this and being ultra available sounds like it will take forever.” In my experience, this time investment was absolutely worth it for the extra hands working on the website before and during the launch.

3. Don’t scale

Wait. Don’t we want to do this for more people faster? Meh. Not really. Just introduce GitHub to one person a time and do it really well and they’ll have a positive experience and you’ll get extra help when you need it on your time-sensitive project and you’ll launch on time and important people will be happy. You don’t need the entire government on GitHub because, per #1, there isn’t an immediate need for everyone to use it.

To be clear, once a few people know it well enough to teach it (via your teaching or because they learned it elsewhere), that’s how this spreads more widely.

One important point: teach one person at a time. Not two. Not three. Not seven.

But that’s not as time efficient!

Ummm. Nope. It’s probably much more time efficient.

By teaching one person at a time, YOU get to learn how to teach GitHub and mess it up without major time-sucking consequences. There are nuances to GitHub that you might forget about while you’re helping someone sign up for the first time. With one person, you mess up, you fix the mess up, you move on, and you don’t mess up with the next person. With three people, you mess up, and you have three confused people who might then tell their colleagues that GitHub is confusing and terrible. You curse yourself, you curse me because I told you so, you fix the mess up for Person One, you fix the mess up for Person Two, you fix the mess up for Person Three, you move on, and you teach one person at a time in the future.

In the City of Boston project, I hit a few dead ends and confusing cul de sacs (jargony description below) with the first person I taught. Since I was teaching him one-on-one, I fixed what I needed to fix for him and didn’t make that mistake again with the next four budget govvies.

Skip the next two paragraphs unless you’re the one teaching GitHub.

<jargon class=”mess-up-example” id=”one”>

GitHub mess-up example one: The City of Boston uses teams in GitHub to collaborate on its repositories. When someone creates an account on GitHub, they can’t contribute to that repository without forking it and submitting a pull request, which is not a beginner-friendly interaction. You have to add the beginners as collaborators if you want to avoid GitHub auto-forking the repo when they try to make an edit, which can be confusing for them and more time-consuming for you to explain forks, etc.


<jargon class=”mess-up-example” id=”two”>If you don’t set up a default branch for all commits to a repo, someone will get curious, change their branch, work for a while, and you’ll spend time trying to find it after they freak out when they can’t see it in production. So, set a default branch for all commits while the beginners are editing. Have them commit directly after editing on the web (explain commits!) rather than via the command line or desktop app, which are unnecessary for non-devs.


That’s how this all works. To review:

  1. Have a really good reason to try GitHub
  2. Make it really easy for someone to learn
  3. Don’t try to do too much too soon

As a short aside, how do you feel when you get a compliment? What about an emphatic high five?

It feels great… But what drops some serious dopamine in your brain?

Seeing a website’s content and structure update because you, possibly a person who probably doesn’t code, just wrote some code on GitHub.

Help someone get a really big hit of dopamine, and teach them how to use Github.

I’ve seen a lot of positive things from teaching GitHub to those govvies, and it’s clearly helped my project. You can bet I’ll be trying this again in the future.

What’s still TBD, however, is whether GitHub will be of any value to the government staffers now that the project is over. Will they use it on their own projects? Will they use it in the future with my former colleagues on the City’s Digital Team? Does that matter? Or is this just useful in one-off projects and that’s fine because, hey, it saved some time? Does using it really make people think differently about the process or the project, or is this just wishful thinking on my part?

These are things I’d like to know — comment here or write me if you’ve got thoughts.