Photo by Christin Hume on Unsplash
The time required to learn something new can be large, but you can make that cost worth it by teaching it to others.
I would even go so far as to say that it's your responsibility to make it easier for the next person to learn the same topic.
Credit to Tanya Reilly and her book The Staff Engineer's Path for the idea for this article. Tanya describes amortizing the cost of creating a curriculum by teaching it multiple times (p. 268), but I think the same applies to documentation, just on a smaller scale.
First, let's get a definition of the word "amortization," from Cambridge :
the process of reducing a cost or total in regular small amounts
The idea here is that the up-front cost of a purchase or action can be made more "worth it" over time.
Some scenarios
Here's a situation: your team uses some piece of technology, and let's say it's older or more challenging to find reliable documentation for. You spend multiple days investigating a workaround to an issue or a setting that you know you want to change, but can't find anything relevant on the internet. You decide to check the code out locally yourself, and you progress further down the rabbit hole. You eventually find the functionality that you're looking for, and you're able to achieve the desired outcome.
Here's a potentially more frustrating situation: you've been tasked with modifying an older system that has very little tribal knowledge left at your company. You find some documentation, and it looks promising until you realize it's years out of date. You once again end up doing code archaeology to find what you need. You find it, spend a nightmarish amount of time testing it, and eventually make your change successfully.
What's missing from these two scenarios? Making the life of the next person better. You spent significant time gaining a lot of valuable context to accomplish your task—you should share that context!
Audience one: yourself
Taking either of the above situations, let's say that you made your change and were able to move on with your life. You get to work on other projects, and life is good. But then business needs change, and you have to revisit your old friend, the poorly documented system.
But it's been so long that you lost all of your hard-earned context.
Don't you wish that past you had left bread crumbs for future you? The code archaeology will likely take you less time your second time, but it will still be costly (and cause the frustration all over again). Previously, spending even ten minutes to have written some documentation could have saved you days of frustration. Be selfish, leave future you some bread crumbs today!
Audience two: your organization
If writing how-to guides for selfish reasons isn't enough motivation, try writing them for altruistic reasons.
Again, taking either of the above situations, let's say that it turns out that your team needs to repeat the process somewhat frequently, and you just happened to be the first person tasked with it. If you didn't enjoy the digital archaeology, it's highly likely that your teammates or colleagues won't either. Especially if you found some traps such as config parameters that seem important but don't actually control anything, or worse, parameters that control something unrelated to their name.
All of this advice is doubly important if you work on a team whose customers are other engineers at your company, such as a platform team. You should be prioritizing self-service for them so that you can focus on providing a quality product.
Here are some example how-to guides you could write today:
- Local development & testing instructions for your services, especially if they differ from your organization's norms
- Deployment steps for your services, in case multiple manual steps need coordination
- A list of custom metrics emitted by your services and what they mean
- How to use one of your team's admin tools (and no, strict RPC schemas aren’t self-descriptive)
Audience three: the public
You should be motivated by both helping yourself and your colleagues, but if not, try writing how-to guides for clout.
If in the course of your daily tasks you’ve learned something generalizable or publicly applicable, blog about it! You would be surprised how helpful it can be to someone else. If the Reddit blackout of 2023 taught us anything, it's that a lot of valuable knowledge exists on the internet, and sometimes it only exists in one or two Google-crawled places. You have valuable knowledge, and others should feel honored for you to share it.
I wrote "Bash Environment Variable Defaults" because I wanted a "snack" article that was easy to write, and even though the topic is relatively niche, the article is in my top five articles by hits. On the other hand, I wrote "Docker Shell vs. Exec Form" mostly as an article to support "You Don't Need an Init System for Node.js in Docker," but the former gets nearly 10x the hits. There is so much more information about Docker and related technologies that I thought it would get lost in the noise. But you never know what people will find valuable!
Bash Environment Variable Defaults
Apr 5, 2023 · 3 min read
Bash scripts can set defaults for environment variables that are optionally supplied at execution time.
Docker Shell vs. Exec Form
Mar 22, 2021 · 4 min read
The RUN, ENTRYPOINT, and CMD, instructions all have two different forms they can be written in, and those forms change how each of those instructions behaves.
You Don't Need an Init System for Node.js in Docker
Mar 20, 2021 · 5 min read
But you do need to think about how your application handles exit signals.
There are also selfish reasons to share information publicly, and it's ok to be selfish! Your company may have a public engineering blog in constant need of volunteers, and maybe contributing published articles can help you with your next promotion. Or maybe you're ready to move on from your company and you're looking to pump up your credentials to hiring managers. Or maybe you're trying to build a presence on social media or in engineering circles. Being publicly visible can help all of these goals!
Getting started
It can be difficult (and overwhelming!) to start writing something from nothing. see "An Effective How-To Guide Template" for a template you can use to get started writing how-to guides today!
An Effective How-To Guide Template
Dec 11, 2024 · 8 min read
Having a template when writing technical how-to guides can increase clarity and therefore usability.
Closing thoughts
There's a Ralph Waldo Emerson quote from his essay titled "Compensation " that is often referenced when talking about the "pay it forward" movement:
In the order of nature we can’t render benefits to those from whom we receive them, or only seldom. But the benefit we receive must be rendered again, line for line, deed for deed, cent for cent, to somebody. Beware of too much good staying in your hand. It will fast corrupt and worm worms. Pay it away quickly in some sort.
In that paragraph, Emerson is talking about paying debts, and the rest of the essay is about keeping one's life in balance. It's not quite the same as writing how-to guides, but I appreciate his opinion that it's one's responsibility to pass benefits on to others.
