How to Write a Good ‘Open’ Task
The act of creating tasks in an open repository is not itself an invitation to get involved. Lets be honest about the ‘types of tasks’ we’re creating, and then just design properly for those we intend for participation.
In Whistler earlier this year, we gathered together a group of code contributors to better understand what barriers, frustrations, ambitions and successes they experienced contributing code to Mozilla projects. Above all other topics, the ‘task description’ was surfaced as the biggest reason for abandoning projects. This, the doorway for participation is given the least attention of all.
As a result, I’ve paid close attention recently to how projects use tasks to invite participation, and experimented a bit in our own Participation Github repository. Probably the best opportunity to understand what makes a task truly ‘open’ is to to witness in ‘real time’, how contributors navigate issue queues. I had such an opportunity this week at the ‘Codeathon for Humanity’ at Grace Hopper Open Source Day, and previously leading an Open Hatch Comes to Campus Day at the University of Victoria.
A quick overview of tasks I’ve noticed:
Meta Task: Meta, Parent or or ‘Feature Tasks’ are a great way to track the overall progress of an initiative or project goals. Unless identified as being this type of task though it can lead to a frustrating journey for someone interested in participation.
Project (Team Member) Tasks: Tasks that require whole or partial involvement of a team member (staff or core contributor) to be completed. There’s nothing wrong with this type of task, but calling them out as being dependent on specific individuals – saves time. Examples: ‘root access’ server tasks, or project management tasks.
The Garbage Tasks: A garbage task is one that appears to have no obvious purpose, deadline or clear outcome. A mystery to the rest of us, these tasks appear to be connected to the single moments in time for the author. These exist everywhere – and I witness the havoc they play on contributors. Often created in a rush or with only the author’s intentions in mind, many of these tasks linger in ‘open’ states. It takes a contributor a long time to discover the irrelevance of tasks like these.
Storytelling Task: Different than a meta-task, and not quite a project task, I’ve encountered quite a few ‘issues’ with a primary goal of storytelling or conversation with an extended opportunity to provide feedback through comments. These are great for transparency and inviting interest, but if there is no clear call to action, it’s probably better as a blog post.
Open or Contributor/Volunteer Task: Is a clear ‘ask’, with action items suitable for completion by an individual. Components of a good open task are:
Helping people filter to Open Issues is a huge win for project and contributor. We’ve been using a tag called ‘volunteer task’ for this purpose, although we may change the name based on feedback. It’s our most viewed tag.
Don’t use abbreviations in titles, and have a clear action reflected.
Referenced Meta/Parent Task
Creating and referencing a Meta Task Is a great way to connect open tasks to the impact of the work being done. They also help generate a sense of collaboration and community that makes work feel meaningful.
I use this in anticipation of questions, and often include reading documentation. Prerequisites are also a way to help people quickly identify which tasks are best suited to their personal goals and curiosity. I include basic skill levels needed as well – with room for learning.
Challenge yourself to bring the key points into the short description. Use Bullet points to break down points vrs writing long paragraphs of text. Link to longer documentation (and make sure your permissions allow anonymous view).
I’ve written a lot about designing participation in steps, and believe that breaking things down this way benefits contributor and project. I know this probably feels tedious especially for smaller bugs, but minimally this means linking to a template explaining ‘how to get started’. Example steps might be:
- Read Documentation
- Build your local environment
- Update the README with any issues you found during the build
- Introduce yourself on Discourse
- Self-Assign yourself this task and leave a comment.
Value to Contributor
I sometimes include this, and my opinion is this is where ‘mentored bugs’ could plug in vrs a bug being only about mentoring. In the virtuous circle for participation, I think this reminds us to consider this perspective of contributors in all we design.
Although some of this might feel like a lot of work, it actually filters out a large number of questions, helps contributors connect more quickly to opportunity and helps build trust in the process.