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.

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

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.

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?”

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.

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.

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:

[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.