A public issue tracker is a vital communication tool for an open organization, because there’s no better way to be transparent and inclusive than to conduct your work in public channels. So let’s explore some best practices for using an issue tracker in an open organization.

Before we start, though, let’s define what we mean by “issue tracker.” Simply put, an issue tracker is a shared to-do list. Think of scribbling a quick list of errands to run: buy bread, mail package, drop off library books. As you drive around town, it feels good to cross each item off your list. Now scale that up to the work you have to do in your organization, and add in a healthy dose of software-enabled collaboration. You’ve got an issue tracker!

Whether you use GitHub, or another option, such as Bitbucket, GitLab, or Trello, an issue tracker is the right tool for the task of coordinating with your colleagues. It is also crucial for converting outsiders into colleagues, one of the hallmarks of an open organization. How does that work? I’m glad you asked!

Best practices for using an issue tracker

The following best practices for using a public issue tracker to convert outsiders into colleagues are based on our experience at Gratipay over the past five years. We help companies and others pay for open source, and we love collaborating with our community using our issue trackers. Here’s what we’ve learned.

0. Prioritize privacy. It may seem like an odd place to start, talking about privacy in a post about public issue trackers. But we must remember that openness is not an end in itself, and that any genuine and true openness is only ever built on a solid foundation of safety and consent. Never post information publicly that customers or other third parties have given you privately, unless you explicitly ask them and they explicitly agree to it. Adopt a policy and train your people. Here is Gratipay’s policy for reference. Okay! Now that we’re clear on that, let’s proceed.

1. Default to deciding in public. If you make decisions in private, you’re losing out on the benefits of running an open organization, such as surfacing diverse ideas, recruiting motivated talent, and realizing greater accountability. Even if your full-time employees are the only ones using your public issue tracker at first, do it anyway. Avoid the temptation to treat your public issue tracker as a second-class citizen. If you have a conversation in the office, post a summary on the public issue tracker, and give your community time to respond before finalizing the decision. This is the first step towards using your issue tracker to unlock the power of open for your organization: if it’s not in the issue tracker, it didn’t happen!

2. Cross-link to other tools. It’s no secret that many of us love IRC and Slack. Or perhaps your organization already uses Trello, but you’d like to start using GitHub as well. No problem! It’s easy to drop a link to a Trello card in a GitHub issue, and vice versa. Cross-linking ensures that an outsider who stumbles upon one or the other will be able to discover the additional context they need to fully understand the issue. For chat services, you may need to configure public logging in order to maintain the connection (privacy note: when you do so, be sure to advertise the fact in your channel description). That said, you should treat conversations in private Slack or other private channels just as if they were face-to-face conversations in the office. In other words, be sure to summarize the conversation on the public issue tracker. See above: whether offline or online, if it’s not in the issue tracker, it didn’t happen!

3. Drive conversations to your tracker. Social media is great for getting lots of feedback quickly, and especially for discovering problems, but it’s not the place to solve them. Issue trackers make room for deeper conversations and root-cause analysis. More importantly, they are optimized for getting stuff done rather than for infinite scrolling. Clicking that “Close” button when an issue is resolved feels really good! Now that you have a public issue tracker as your primary venue for work, you can start inviting outsiders that engage with you on social media to pursue the conversation further in the tracker. Something as simple as, “Thanks for the feedback! Sounds similar to (link to public issue)?” can go a long way towards communicating to outsiders that your organization has nothing to hide, and welcomes their engagement.

4. Set up a “meta” tracker. Starting out, it’s natural that your issue tracker will be focused on your product. When you’re ready to take open to the next level, consider setting up an issue tracker about your organization itself. At Gratipay, we’re willing to discuss just about any aspect of our organization, from our budget to our legal structure to our name, in a public issue tracker we call “Inside Gratipay.” Yes, this can get a little chaotic at times—renaming the organization was a particularly fierce bikeshed!—but for us the benefits in terms of community engagement are worth it.

5. Use your meta tracker for onboarding. Once you have a meta issue tracker, a new onboarding process suggests itself: invite potential colleagues to create their own onboarding ticket. If they’ve never used your particular issue tracker before, it will be a great chance for them to learn. Registering an account and filing an issue should be pretty easy (if it’s not, consider switching tools!). This will create an early success event for your new colleague, as well as the beginnings of a sense of shared ownership and having a place within the organization. There are no dumb questions, of course, but this is especially true in someone’s onboarding ticket. This is your new colleague’s place to ask any and all questions as they familiarize themselves with how your organization works. Of course, you’ll want to make sure that you respond quickly to their questions, to keep them engaged and help them integrate into your organization. This is also a great way to document the access permissions to various systems that you end up granting to this person. Crucially, this can start to happen before they’re even hired.

6. Radar projects. Most issue trackers include some way to organize and prioritize tasks. GitHub, for example, has milestones and projects. These are generally intended to align work priorities across members of your organization. At Gratipay, we’ve found it helpful to also use these tools to allow collaborators to own and organize their individual work priorities. We’ve found this to offer a different value than assigning issues to particular individuals (another facility issue trackers generally provide). I may care about an issue that someone else is actively working on, or I may be potentially interested in starting something but happy to let someone else claim it first. Having my own project space to organize my view of the organization’s work is a powerful way to communicate with my colleagues about “what’s on my radar.”

7. Use bots to automate tasks. Eventually, you may find that certain tasks keep popping up again and again. That’s a sign that automation can streamline your workflow. At Gratipay, we built a bot to help us with certain recurring tasks. Admittedly, this is a somewhat advanced use case. If you reach this point, you will be far along in using a public issue tracker to open up your organization!

Those are some of the practices that we’ve found most helpful at Gratipay in using our issue tracker to “engage participative communities both inside and out,” as Jim Whitehurst puts it. That said, we are always learning. Leave a comment if you’ve got an experience of your own to share!