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:

picture

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:

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

picture

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.