Guidelines for GitHub Issue Specification

Part of effective software project management is the ability to describe what a team member needs to do prior to doing it. Without a clear understanding of what is to be accomplished, team members are more likely to do the wrong thing, which can end up requiring rework and slowing project progress down.a

Effectively and efficiently specifying “what to do” is an art, not a science. Ideally, you provide enough detail to ensure that the team member can implement a feature appropriately, but not so much that you “overspecify” the task and prevent the team member from implementing the most appropriate solution as they do the work.

Issue Driven Project Management (IDPM) is called that because the “driver” of the project is GitHub Issues. You use GitHub issues to specify the tasks: what is to be accomplished by each team member at any point in time.

Software project management in general, and Issue Driven Project Management in particular, doesn’t work well when you don’t take the time to clarify what a task involves. This is not obvious when you are new to project management.

For example, consider this “task specification” from a newly formed team:

This shows a classic breakdown in software project management: this team created issues, but did not take the time to specify what the task of “Landing Page Footer” actually means.

Here are some ways to improve this task specification:

• Improve title. Use a verb in the title to better clarify what the task involves. Is the goal of this task to “Create a paper mockup of the Landing Page Footer” or “Implement a React Component for the Landing Page Footer”?

• Correct the branch label. Our template application includes an Issue template to automatically insert the text “Please do work for this task in a branch named issue-XXX”. This is because in IDPM, the work corresponding to a task should be performed in a GitHub branch whose name corresponds to the issue. You are supposed to replace the “XXX” with the actual number associated with this task. Since the number assigned by GitHub to this issue is “6”, that line should read “Please do work for this task in a branch named issue-006.”

• Provide a description of the work to be done. There is no description of what it means to “Landing Page Footer”. What should appear in the Landing Page Footer? What is a first pass at the appropriate layout for the landing page footer? Are there any special colors or fonts that should be used? In most cases, you can describe what work should be done in 5 to 10 minutes as part of the planning meeting where this task was generated.

To see this in action, here is an issue from the BowFolios sample application that addresses these points:

In addition, you can see that before closing the issue, the developer assigned to this task pasted a screen image of the completed page. This is a nice way to communicate to the team what you did and how you did it.

Finally, GitHub includes a feature called “task lists” where you can break down the activities to be done for an issue into a checklist. This is not required for IDPM, but some of you might find it useful. Documentation on this facility is here.