Part 3 — Structuring your GitHub Project for success

Solving life's problems by keeping agile

In the previous section I covered how to set up GitHub Project, specifically for personal development.

This sort of aide can easily become a burden if you overload it: keep the columns straightforward ("Ready", "WIP", "Done" are typical status columns). I call mine 'Future', 'TODO', 'WIP', Done'.

This layout encourages you to identify what Agile methodology calls "definition of done". In software this can be codified in tests upfront (Test-Driven Development), which alleviates the ambiguity of when to move something from WIP to Done.

You could also add a 'Complete' status column if this is a meaningful distinction for you (perhaps if you plan to carry out some retrospective on the task), or you could simply expand your definition of done to include that final step.

At work, we use an 'in progress' label (added via repo settings), which isn't available by default and perhaps is best avoided.

You should ruthlessly guard your WIP: it's not a vague concept, it's very specifically the task at hand. As the DevOps Handbook advocates, good practice is to do small batch work, and taken to the extreme this is single-piece flow (where you deliberately execute a single WIP at a time).

I personally find this assists execution (as discussed in the introductory part of this series), and will also use a whiteboard when working intently to maintain a laser focus on the current WIP Note: when I do this I make sure the WIP is not the overall deliverable/goal (you cannot laser focus on a high-level idea, only on an immediate horizon).

Agile plans lay out the 'happy path' (a.k.a. golden path) when fleshing out ideas from the first step to the solution of the root cause of the problem.

If you have trouble identifying this, a good approach is that of working backward (which mathematician Pólya discusses in How To Solve It, with backward chaining as its formal analogue).

A mistake I have noticed when formulating problems for task-oriented boards is that, as humans do, I identify the problem (or blocker) in the form of a narrative. The narrative is an 'issue', i.e. it poses a problem.

A kanban board is not for narrativised problems but for solution constructions. You need to rearrange all the hypotheticals into a single chain from starting point to solution via hypothetical interventions.

instead of writing “I can't/haven't yet done X because I don't know Y. I could figure out Y by doing Z…” — reverse it into a checklist and then just check off those tasks rather than making a narrative out of your blocker which can only be dwelled on.

It doesn't take an expert in modal logic to see that the 'task list' that solves the solution here is "do Z, learn Y, do X". It's very natural to pose a problem like this, but it introduces the tasks in a completely counterproductive order.

This happy path could be a checklist on a single task, or you could split out a task into multiple and indicate their connection by their order in the TODO column. You can also keep a checklist on a main planning task, and create the items one by one from this checklist as you go.

Analogously to a sprint, your kanban should give a timeframe for the work it shows, such as "this weekend" or "this month" [which might practically mean "the weekends and days off this month"]. This timeframe can be organised using Milestones if you're elevating Project items from drafts to issues. Consider this carefully, as you either need to create a fresh Project for each sprint (this can be nice if you want a blank slate) or if you organise with status columns and milestones you might prefer to reuse the same kanban.

I opted to use a single kanban, and will add further notes on what works as I go forth...


This post is part of Supporting and structuring personal development and open source contributions with GitHub Projects, a series covering how I began using the GitHub Projects tool for tracking my personal development and shipping outside of work. Read on for part 4, discussing how to maintain your GitHub Project