It is no secret that the Wiredcraft team is hooked on Github. And while we definitely use a lot more than GitHub to collaborate, the issue queue remains the single most important collaboration medium for our team.
Which means, learning how to properly write issues and comment on them is a pretty important part of the onboarding process for our new recruits.
We usually stick to the following structure:
Context: explain the conditions which led you to write this issue.
For example: “Since we’ve moved to the latest version of Express.js, we’ve experienced a few performance issues (#14 and #15) on production.”
Problem or idea: the context should lead to something, an idea or a problem that you’re facing.
For example: “We’ve had no way of easily seeing the performance impact before releasing our changes to production.”
Solution or next step: this where you move forward. You can engage others (request feedback), assign somebody else to the issue, or simply leave it for further investigation, but you absolutely need to propose a next step towards solving the issue.
For example: [email protected] see with @johnny if he has a tool that could provide us insights on the performances in the development environment. We should include something similar in our development and deployment processes for future projects.”
This last point is the most important, and often most disregarded, aspect of an issue thread. This is the seed of collaboration. Omitting it seriously hinders your chances of engaging others.
It is also important to try and put down all of the relevant information you can think of when creating the issue. It enables others to take over and provides invaluable context may you get to work on it days or weeks after creating it.
A bad issue: too much in the title, no context, actionable or relevant people notified.
A good issue: simple title, context, actionable and relevant people are included.
/cc @bob @johnin our issues).
We feel very strongly about these guidelines; they may seem overkill at times but sticking to it in a systematic manner has helped us improve drastically the quality of our collaborations, may this be to organize a business trip between members of our San Francisco and Shanghai offices or coordinating work between two engineers sitting next to each other.