Paper Trail
Hey!
Welcome back to another week of musings.
We had some high-temperature days here in the bay the past week, and we enjoyed going for walks and spending time outside.
I hope you had a good weekend and some time for yourself.
Was this forwarded to you? You can subscribe here!
Things I discovered in the past week
- I signed up for otter.ai(referral) and have been using it to dictate notes and copy-paste the transcript to my Obsidian daily notes. It's pretty good for understanding me and drafting action items or follow-up tasks.
- EFF Surveillance Self-Defense Guide With these unprecedented times we're living in, I was looking around for a resource to share with friends and family.
Over the last few weeks, I've been borderline obsessing over documentation.
Several concurrent events triggered this action on my side: a couple of people left their teams, incidents where we forgot a decision was made that triggered the issue, and the difficulty of enforcing some policy if it is not written down.
I've been reading about documentation like:
Useful friction
Documents like ADRs and RFCs add useful friction to the process.
As engineers, we're often eager to jump to a greenfield project opportunity or to sunset a codebase we don't understand, labeling it legacy. If you're going to another city, you don't run to the car and start driving. Instead, you plan your trip for stops, where to spend the night, food, etc.
ADRs and RFCs help slow the process and make us think about the why of what we want to do. The template drives us to write down other options considered.
Decisions No Longer Serving Us
ADRs also have this idea of being superseded by another decision, which makes the process worthwhile from my perspective.
For example, when we started with Node.js, only Express was available, but now that other frameworks are viable options, we might want to change to Fastify. The process would involve documenting why we wish to migrate and explaining why the past decision no longer serves us.
Historical Context
In other cases, they're helpful because people come and go from the company, or teams are reorganized as new business priorities arise.
We can't trust that the one manager who's been at the company for 15 years will remember that random snippet of code with the TODO: Fix when we have time that is now throwing exceptions at random intervals. In other cases, we might have forgotten why we chose to run our own Jenkins infrastructure or why we decided to build a new OAuth Server, but only 30% of the services were migrated two years later.
Progress over Perfection
Usually, these ADRs or RFCs must be reviewed, approved, etc.
Many teams are resistant to introducing said processes. It feels like a heavyweight approach if they've been working well all this time. Changing culture is hard, and I suggest a lightweight approach.
Apart from you, find other folks having similar issues with the lack of documentation. Start documenting without too much review, or start by documenting past decisions. Start building the muscle, and show, don't tell works better in these cases.
Your turn!
How do you deal with lost context in your company? Do you review past decisions? Or are you or your teams always scratching your heads, asking why we did this or that? Let me know your thoughts by replying to this email!
Happy coding!
website | twitter | github | linkedin | mastodon | among others