Today, I’m working on our new deck. It’s a little uncomfortable, because there’s no furniture. I’m sitting on a blanket.
The furniture is in the yard, being spray-painted. Before my husband left for the day, he said “If you have time, you could spray some more paint on the chairs.” Seems like I could contribute to that, since I wish I had chairs.
Which chair needs painted? I don’t know, I guess the ones on the tarp.
Where is the paint? Perhaps it is in this bucket of objects… ew.
He mentioned yesterday that he needs to get more paint. Maybe we don’t have any. I don’t know what kind he was using.
To help, I need to know what the next step is, what to use for it, and when to stop. My husband has “state” on this (as Stripe called it internally); he knows what’s going on and how to progress it. No one else can help unless he’s there contributing that knowledge.
Software projects realllly have this problem. You might be good at TypeScript, but if you don’t know what this project does, what it needs to do next, how to build & run & test, and so much more–you can’t move it forward.
Documenting all that, tracking in-progress and up-next work, keeping the build system smooth: it’s a lot. Teamwork is way more work than working alone. But, working alone tops out. One person can only do so much, and one person cannot support production, and one person moves on to other things.
In my personal projects, I have a compromise: leave enough of a trail that my future self can come back and make further changes. This means
- there is a README that says why this repo exists and what it does
- The README links to production, if there is one
- The README says how to build, test (if there are any), and deploy (if production exists)
- There’s a ‘run’ script that runs it. I work in too many languages to wonder every time whether this one is ‘docker compose up’ or ‘npm run start’ or ‘dotnet run’.
- Commit messages tell me a story. The last few reveal what I was doing, and whether I finished it.
- If I really want to pick up where I left off: end with a failing test.
Then, when I come back to this project after days or weeks, and something is confusing or doesn’t work–I fix the README or add to it. At the least, I remove the instructions that don’t work: that’s a contribution too.
It helps to have conventions about where to look for this information. README files are great for this. In someone else’s project, I can follow the trail: “it says to run this script. What does that do? Oh, docker compose up. Next, look at docker-compose. Oh wow look at all this stuff… ok which container is running nginx? Let’s look at the config and follow those trails.” Picking up someone else’s project is its own skill.
I don’t have that skill with the chairs.
Starting a project, it’s fair to run with it. If you want help from other people, then you have to consider what knowledge they’ll need. Put the supplies in an agreed-upon place, maybe leave notes about how many coats each chair has received and still needs. These affordances give contributors something to grab on to, and some hope of chipping in.
And in your teams, agreeing on where to track things and how to share changes and all the rest of the overhead–that is not time wasted. That is the work of working together.