Making bite-size issues to tackle

This issue may prove to be divisive, but it seems worth discussing from the viewpoint of a newblood programmer and a potential employer alike.

When using GitHub "Issues," there are two common uses: public users viewing the repository can submit bugs, problems, or desired features, as general or specific as they'd like; the other use is for repo owners to give tasks to one another. This post focuses on how best to utilize the latter for maximum productivity, in a way that still gets work done.

The trick is to make your issues as bite-size and manageable as possible.

The trickiest part of solving a problem is wording it in a way that has an answer.

Concrete Progress

A bite-size Issue on GitHub gives your contributors maximum ease of making progress. It's not so much about the time taken to solve an issue, but rather the number of things someone has to consider when solving that issue.

Consider the following two Issue imperatives:

1. Have Folder know about all of its contents, including those in subfolders
2. Add recursive getAll method to Folder to retrieve all subfolder content

The first statement begs several questions: how should Folder know about it? What contents does it already know about? Where should it be stored? What kind of method should we implement to have it find its contents?

The second statement begs fewer questions—that's because it is highly focused on solving one specific issue revolving around the question of a Folder's awareness of its contents. Rather than stating a general problem that needs dealing with (which can lead to confusion regarding when it's solved), a specific problem may take a smaller bite out of the problem but it takes a concrete bite out of the problem.

It's something that, once it's completed, you can be reasonably sure it won't need to be dealt with in this way, any more.

Bite-size Chunks

Example

For the above problem regarding Folder, it would be much better to create one unique issue for every concrete facet of the problem. Something like this:

1. Have Folder's addItem method add each new item to its own contents list
2. Add recursive getAll method to Folder to retrieve all subfolder content
3. Implement data structure for Folder to store references to all contents
4. Implement "changed" boolean to inform superfolders when a subfolder has changed
5. Have addItem and addFolder methods invoke super.isChanged, which invokes super.isChanged (etc)

Notice that some of these imperatives would not take long to do (like #4), and others might take quite a while, or at least substantially longer (like #2, perhaps). That's okay. What's important is that each issue doesn't really require making big decisions—they're already made—it requires getting something done.

Benefits

Besides a manager being able to watch as bite-sized issues slowly get eaten away, and giving the programmer a stronger sense of accomplishment (and a less vexed attitude), it allows programmers to pick and choose between multiple concrete problems, and do the ones they're best at.

Further, it decreases overhead caused by daily office distractions—in the above example the Issues are assuredly tiny, but having issues that can be dealt with in less than an hour (or maybe two) allows a programmer to stretch and even take a lunch break, without wasting time getting back into the flow of things.

Additionally, it allows better tracking of issues—you'll know more precisely who solved what problems, and at what time, and even how long it took them.

Drawbacks

While it's great to make bite-size Issues, working in this way increase overhead in actually creating them, as a programmer has to spend more time breaking the issue down and reporting the issue. Some programmers do not work this way, and can deal with pretty large problems very deftly. Others are more methodical, and will thrive with more broken-down Issues. It's definitely a trade-off.

Aside from that, you might risk artificial inflation of progress tracking: you'll see employee A has 50 Issues completed in the last week, but it becomes increasingly meaningless because they were broken down into tasks that could be done too quickly; while employee B has only 5 issues done in the last week—even though they might be much more substantial issues, someone looking at an employee review will see 50 vs. 5 without context.

Effective use of this technique requires the problems to be delegated, if not to different programmers, then to different times. Consider having your team brainstorm Issues together, draft a list of them, and then break to whittle away at them.

Software Engineering Tie-in

Remember this when you decide to take up any practice of engineering, for absolutely any field. Engineering is the practice of defining and narrowing a problem until it is something that can be solved, and then going about solving it in a thoroughly-tested way.

For a civil engineer, it might be going from something like "We need a new MAX line running across the Willamette River, into Milwaukie," to "We need a bridge spanning this portion of the river, with x height, stability against these kinds of weather, and a maximum load of y tons," and so on until the bridge is built.

But for a software engineer, this means going from a very general need to something concrete, which can be done. Breaking down a task into manageable pieces is one very effective way of doing that.

Any just like any form of engineering, it is more a critical frame of mind and an eyeball use of heuristics than a concrete methodology. Consider this example Issue list from one of my projects, and notice how very brief some of the issue descriptions are. This works because, at the time, I was the only programmer on the project and only needed a reminder.