This post is adapted from the transcript of a short talk I shared at the Code for America Summit‘s Brigade Day on May 29, 2019. While this presentation is specific to brigade teams, it’s relevant for any remote development team struggling to bring new team members up to speed.

It’s worth noting that because this was a 5-minute talk in which the slides advance on their own, this offers a birds-eye view of the topic (with bonus material added below).

Do you actually enjoy writing documentation for your project? That’s okay; I realize most normal people aren’t as enthusiastic about documentation as I am. But as I’ve been managing the West Oakland Air Quality project for the past six months or so, I’ve run into some very brigade-specific issues. And I’m sure these aren’t unique to us.

Summary of brigade-specific challenges: historical context, knowledge sharing, accountability, onboarding

For example:

  • We tend to lose a lot of historical context when team members move on, so docs help us maintain continuity.
  • We all have a certain level of accountability to our project partners, and docs can help communicate out and collaborate.
  • We all struggle to share information among team members who don’t necessarily see each other every day.
  • And we all tend to get a lot of the same questions—over and over again—when a new team member joins.

As we’ve experimented as a team, we’ve found documentation helps solve for many of these.

Let’s talk onboarding

Scene from The Shining, of Danny and Wendy Torrence entering the labrynth of the Overlook Hotel.
Image © Warner Bros. Entertainment Inc.

When a new volunteer first steps through our doorway, they tend to have two main questions:

  • “What’s this project about?”
  • “How do I contribute?”

Those can be big questions. To answer them at the right level, we really need to think about that doorway. Our new volunteer probably doesn’t know much about our brigade, or how projects work generally. And they certainly don’t have any specific project context. They only see what’s immediately in front of them, framed by the doorway. So we want our documentation to give them that big picture.

Scene from The Shining of Jack Torrance gazing down at a model of the Overlook Hotel's labrynth.
Image © Warner Bros. Entertainment Inc.

But the big picture can be scary! If we throw everything about our project at someone and ask them to sort it all out on their own, it can be overwhelming. Your eager new volunteer is likely to run screaming (I speak from experience). This is particularly true for more complex projects, or for teams that have a long history of activity.

Creating doorway docs

So we want to onboard people gently. And we do that by treating onboarding like any good user experience: we need to give people just enough information to answer the questions they have right now: “What’s the project about?” and “How do I contribute?”

Three doors: door one is labeled with the Meetup logo, door two is Slack, and door three is GitHub.

For the WOAQ team, our main doorway is generally hack night, where we start by getting new volunteers set up in our Slack channel. But we people also find us through GitHub. People can show up through any of these doorways, so each one needs to provide access to the right level of information.

For folks who first join us through Slack, we’ve pinned a single link to the channel topic. That link goes to a Google Doc that answers those two big questions (say it with me: “What’s this project about?” and “How do I contribute?”). Because we tend to have a much wider variety of skillsets show up at hack night (and therefore, on Slack), the Google Doc includes several different ways for folks to get involved beyond just code development.

Screenshots of the Slack channel topic containing a link to our Project Overview doc, and the GitHub ReadMe.

The folks who enter through our GitHub doorway tend to identify as developers. Our GitHub ReadMe, therefore, provides a similar project overview, but the contributing material is more specific to getting up and running with a local development environment. It’s critical that both of these doorways link to each other, and that they maintain parity in the level and type of info they provide. But we have to also tailor that content to the needs of that particular doorway. It’s a balancing act.

After onboarding

Once volunteers are through the door and get settled in, they have different kinds of questions that require different kinds of documentation. These tend to fall into two big buckets: product-specific documentation, and process-specific documentation. While those can be broken down further, there’s no one right way to categorize these.

Examples of Product docs include functional requirements, design specs, and research. Examples of Process docs include relationships, how-tos, and decisions made. The center column reads "What, How, Why" respectively.

Within these buckets are endless variations on documentation that can help capture the decisions we make about our project as it develops. Because WOAQ is working with lots of data sets, for example, we had to spend some time mapping how that data would move through our different platforms. So we created a system architecture diagram to get everyone on the same page.

A five-minute lightning talk isn’t nearly enough time to cover all the types of documentation one might find useful over the course of a project. This list is not comprehensive. It is highly interpretive—terminology varies greatly depending on who you’re talking to and what their particular lens is (software developers think of domain models slightly differently than content strategists, for example). This list is 100% dedicated to my team member, Niels:

Entities and structure


[Note: Feel free to suggest better links in the comments. And yes, feel free to quibble about the categories, too.]

Focus on: ReadMe docs

The ReadMe doc is critical but there are no hard and fast rules for what should be included. I say this with full transparency that I’m new to open source and GitHub workflows. I’m still learning about standards, and exploring what works and what doesn’t for my own projects. Regardless, a ReadMe should follow the same basic principles for creating any reader-friendly content.

The biggest decision to make is who your ReadMe is intended to onboard. Content decisions, after all, should be informed by your audience. I’m struck by how many ReadMe docs make the mistake of assuming a high degree of code literacy. Worse still, they often assume all readers manage their GitHub workflows similarly. They often gloss over important details about how contributors should structure their issues, manage forks and branches, and so on. Please don’t do this.

If you want your project to be accessible to contributors with different skill levels, you’ll want to spell out a few things explicitly:

  • What and why
    Provide a birds-eye view of what your project does and why it exists.
  • How to contribute
    If your project needs support beyond code development, consider mentioning how. Because GitHub is a code-centric doorway, though, I’d recommend keeping this at a high level and simply linking to more details for those who wish to use a different doorway to your project.
  • Local environment set-up
    There are plenty of ways one might run a local development environment and experienced developers don’t generally need a walk-through. On the other hand, Code for America brigades often attract beginners, so it can be helpful to recommend a particular option. It’s up to you whether or not you include step-by-step instructions, but you’ll definitely want to include code installation details once the contributor has their environment up and running.
  • Managing issues, pull requests, forks, and branches
    Do not assume everyone uses the same workflows you do. Being explicit about these elements will smooth out the contributing process and prevent miscommunication.
  • Contact info
    Including an alternative communications channel is helpful for folks who may have questions or comments that don’t seem appropriate for opening a dedicated Issue.

Show me your ReadMe

Again, this is not an exhaustive or conclusive list. After my first Code for America Summit Brigade Day, I’m blown away by the talent of this network I’m part of. I know there are some great ReadMes and onboarding docs out there, and I’d love to see them. Share ’em in the comments, please!

So what do we do with all these docs?

Team members tend to bounce back and forth among this collection of documents, so it’s helpful if they’re all maintained in a single location. Our doorway docs also provide access to this document repository. This way, team members don’t need to keep track of where each individual document lives over the life of a project. They need only keep track of the doorway doc they became familiar with on Day One.

Finally, to drive the point home: my original lightning talk was my doorway doc for the Brigade Day audience. This post, whose URL I shared at the end of the talk, is meant to provide a deeper dive for those who wanted more.

The night before this talk, I cut a third of the slides. There’s just so much to cover when it comes to documentation, and five minutes ain’t enough. I mean, I haven’t even touched on end-user documentation. Or filename conventions. And then there’s the challenge of too much documentation and out-of-date documentation. But no matter; let this be a doorway. To that end, here are a few more random resources:

Free advice and strong opinions on content and UX

My email update is safely occasional (like a sundae).