The swarm doc

Weeks of programming can save you hours of planning. This leads to long code reviews, fruitless debates after you've done the work, and grumpy rewrites of features that work just fine.

You build a neverending pile of work in progress that kills your progress and everyone wonders why nothing gets done. Sprints become a running joke and deadlines are 🤷. The business can't plan, resentment builds, trust drops, and ... yeah.

Instead of having those conversations after the code is written, you can have them before. Shift left.

I wrote about this in Coordinating at the end is too late. But I didn't say how. Since I'm now teaching a new team how to do this, here's the document I like to use to structure this conversation.

Swarm doc

Swarms are short technical meetings before a project. Their goal is to frontload design work and catch gotchas early. Swarms speed up code review and cut down on needless debate late in the development cycle.

You should end every meeting with a clear idea of:

• what you're building,
• what you're not building,
• how you're building it,
• a task list,
• a plan for how you’ll know it worked

You can use this doc to guide the discussion. Invite everyone who may have opinions. You are encouraged to make a copy and fill it out during the meeting. This gives you a nice doc you can reference later.

What's the problem we're solving?

Describe in a few words or link user story. Make sure everyone agrees.

Open questions

Write down clarifying questions that come up and need external input

What are the core requirements?

Bullet points what's needed to solve the problem

What are the moving pieces?

In broad terms, what boxes does this touch

How do those pieces interact?

Define the interfaces between moving pieces

How are we doing this?

Define a task list, ideally each piece can be independently built, verified, merged, deployed (even if it doesn't do much on its own)

How hard will this be?

It's good to hip-shot a time estimate. This tunes our gut feel for commitments

The task list helps you split work among team members. Because you define the interfaces ahead of time, everyone is empowered to figure out the details of their area.

I use this as a mental checklist even when working on my own. Having an exact outcome in mind before you start the work is chef's kiss.

Cheers,
~Swizec