The Software Developer's Checklist: An Attempt

I recently finished reading The Checklist Manifesto: How to Get Things Right by Atul Gawande and it's led to a lot of reflection on software development checklists I've used and implemented. I've also been thinking a lot about the checklist I would write for a team now, having read this book, and where some of my previous attempts failed.

An Accounting of My Failures

The first checklists I ever wrote were rather basic, to be honest. I was on a mostly junior team and trying to catch things that are easily skipped or missed by early career devs. This included things like "Review SonarCloud Alerts" and "Link the JIRA ticket to the PR". So, why did these fail?

1. Some of the checks were tied to things already being checked for in our branch protection rules, which made them redundant and frustrating
2. The checks were too obvious and too numerous - I had erred on the side of thoroughness and subsequent retro meetings had me strip out the majority of the checks
3. The checklist was in the PR template, which is WAY too late in the dev cycle for a checklist
4. The checks rarely prevented problems, leading to them being skipped most of the time
5. Some checks were only relevant sometimes, so unchecked items were common, leading to the list not really being looked at during the Peer Review process

To say that my early iterations were ineffective would be generous. By the time the team finished iterating on that checklist, the only item left was "Add the JIRA link". So... not great!

The New Checks on the List

First, I've thought a lot about where to put my shiny new checklist. As I mentioned, I think the PR was way too late. The list was up against sprint deadlines and the general impatience to merge that a lot of devs get when they finish something, which meant it got skipped. The earliest document a dev looks at in the cycle is the ticket or story, so that's where my checklist would go.

Second, Atul Gawande pointed out something that I missed in my checklists but know from experience: most problems in projects are communication-related, not skill-related. So my new checklist focuses there - the communication issues that cause rework, disappointment, and frustration.

Finally, no skippable checks. If a check is on this list it has to be actionable, even if it's just a pause to confirm something isn't needed.

The Masterpiece

## Before Writing Code

- [ ] All requirement, wireframe, and API docs are reviewed and linked to the work item
- Kickoff Meeting with Technical Lead and Project Manager is:
  - [ ] Not Necessary
  - [ ] Scheduled

## Before Merging

- [ ] Demo with at least one other person done in staging
- Architecture Decision Record and/or other documentation is:
  - [ ] Not required
  - [ ] Written and shared with the team
- API version changes are:
  - [ ] Not required
  - [ ] Documented and shared with all affected teams

## After Deploy

- [ ] Demo with at least one other person done in production
- Follow-up work is:
  - [ ] Not required
  - [ ] Documented and prioritised with the Project Manager        

I think this checklist catches the biggest causes of problems I've seen in software development. It's not uncommon for someone to read the story and start writing code without fully reading the requirements, or merging without doing a full run through in staging. Communication within and between teams is also often skipped, which can lead to a lot of frustration as things get out of sync very quickly.

It's also important to note that there's no "seek team approval" step, even when an ADR is needed. I'm of the opinion that if there's a discussion to be had, it can be ongoing and, if necessary, changes made later. There's no need to slow down work waiting for a consensus when continuous iteration is the name of the game anyway.

Speaking of Iteration

While I've given this version a lot of thought, I don't think it's perfect. The wording would likely need to be adjusted for a specific team's culture or dev stack. There are probably important items I missed, or items that aren't relevant to certain groups. This isn't the final version because, as with almost all things in life, there never really is a final version.

This checklist is a start. Feel free to give it a spin and see if it works for your team.