I’ve been inspired by people in my sphere doing “week notes” as summaries of the week, like Steve Messer at GDS. This is the first of (hopefully many) weekly posts as a sort-of journal of my experiences in tech.
Taking time and space to learn
I was on holiday last week, and during that time the rest of my team were working on rolling out a new feature for a open-source library we’re building to enable app-configuration lookup from multiple sources (source on GitHub).
This was notable for a number of reasons:
- Some of the team had written negligible Java before, and were unfamiliar with the ecosystem and tooling like Maven and JUnit.
- We were experimenting with integrating this library into another team’s codebase - that team was at a conference for the whole week.
The feedback I received was that some of them loved diving straight into unfamiliar code and languages, others preferred to take the whole thing in before starting to write tests. We originally wrote the library to be minimal, simple, and extensible - while (1) and (3) were agreed, there was missing documentation on how the library worked under the bonnet.
We used this as an incentive to provide the thorough documentation we currently have by asking ourselves “what would we have needed to write to make enabling new users easy?”
Our experience also reflects observations in Dan North’s Patterns of Effective Teams, mobbing a group together to form a great learning environment.
Try this experiment - ask someone from another team to make a small change or refactoring to your team’s codebase. It’s a really good test on how low the barrier to entry is for new developers who might work on the project in future.
Losing context over time
In a discussion with developers from another team I was asked why we do “roll-forward”, a revert-commit and a new deploy, rather than “roll-back”, deploying a previous known working artifact.
Despite having this conversation before, and understanding it, I had forgotten the exact reason that we still have this practice. (It’s because we want to maintain the invariant that the HEAD commit from our codebase is the artifact in production - the code is the source of truth).
Benji, who recently left us, touched upon this in his last Unruly-centric blogpost
It seems to be relatively easy to communicate traditions and rituals through time—the things that we do that can be observed by new colleagues. It appears much harder to retain organisational memory of the intent behind practices.
Constant curation of sources of knowledge, and reasoning behind practices, is a small price to pay for us having a way of avoiding cargo-culting or degenerate practices.
Growing open-source culture
I am a strong advocate of both open-source and developing code in the open at Unruly - my team has the opportunity to work in the open more than the core product teams, but this is something I would like to experiment with more widely.
We rolled out our library mentioned above to a team using it for their Acceptance Tests, and rather than come and talk to us about a bug and have us fix it, the developer who raised it instead filed an issue against the codebase with an example stacktrace.
This kind of formality was more useful to us than someone coming to talk to us with “I found a bug, here is what it did”. Having an issue created a paper trail and made it easy to attach relevant information and reproduction steps.
It’s worth remembering that a disadvantage of colocated teams is that for people outside of them, whether a different team or an office in another country, there is a tendency to have short chats without record of decisions made or bugs reported.
(My team often use “Can you file a ticket for visibility?” as an attempt to avoid this)