Want to chat? Donate to one of these charities!
Home Notes Popular RSS

December 1, 2022

Is it worth writing about?

writinglearning

You acquire a skill or experience through time and effort, then downplay the impact of writing and sharing the learning process.

Professionals seem naturally to imagine a high bar for what is worth writing about.

I think that's misguided. This article is not criticism of folks with these beliefs, but rather encouragement for folks looking for a reason to write.

There are (at least) a few concrete reasons to write about what you've learned, even when you don't think it's novel.

To practice writing

This is the easiest reason. While practice does not imply improvement, you cannot improve without practice.

Every time you learn something is a chance to write down both what you've learned and also how you learned it.

For professional developers this chance happens all the time. Daily, really. But most developers, even those who want to write more, let the opportunity slip.

Providing variety

When I learn a topic I normally go through dozens of posts, papers, docs, videos or books to find a version that clicks. If I can. I prefer to start with blog posts and often there are not blog posts on the subject. Books, docs, videos, and academic papers aren't often as accessible.

Even if you're writing about a popular topic, there's still a chance your post gets through to someone in a way other posts do not.

For programmers there are notorious topics you can avoid if you'd like ("What is a monad", "Why is lisp interesting", "Kubernetes sucks"). Or not. I've fallen into those traps.

Additionally, as you gain experience as a programmer (or product manager, or whatever), your perspective and approach becomes both more interesting and more valuable.

I don't recall ever thinking: "I wish they'd write less". But I'm always wishing some folks wrote more, or at all.

Some folks with experience, writing about widely varied topics in software include:

But experience need not be a prerequisite. Experts (who don't practice explaining) easily forget how they came to their current understanding. A beginner's experience is valuable for everyone who is not a beginner, sometimes also for beginners.

To cement understanding

Finally, honest writing forces you to either understand the dark corners of what you've learned or to ask for help in these dark corners.

I have repeatedly wrestled with topics in software only to be further forced to explain why (or how) when I write.

And it has often forced me to restructure code or ideas in ways that are easier to explain. I think that's a pretty valuable act for the long-term.

Bad faith

There's a bad faith argument that you sometimes see. Here's a variation that comes to mind.

The internet is already full of crap. People who aren't experts are just making it worse.

I hope you ignore these comments. :) If there's a quality problem that is genuinely causing harm, that's for search engines and trade organizations to deal with.

In the extreme

Simon Willison's TIL site is the most prolific version of this I've ever seen. I don't know if I personally aspire to Simon's level, but I think it's worth seeing.

Topics

Some topics I think are always worth writing about and sharing:

  • Your process, failures and successes, to figuring something out
  • How to hack on some major open source project
  • In-depth comparison of projects or approaches, down to source code, benchmarks, and architecture when relevant
  • Building minimal versions of some production system
  • How some major systems works under the hood, down to the code
  • Mistakes you made in structuring organizations, or production architecture, or testing, etc.
  • How to get the dang configuration right for testing Electron apps in Github Actions

For programming posts specifically: I strongly encourage you to include or walk through working code. Have tests. And have the code build process hooked up to GitHub Actions or SourceHut CI or whatever. This helps ensure your work is still relevant over time.

When you write

Write to explain and teach. When you don't understand something, call out that you don't understand it. That's not a bad thing, and the internet is normally happy to help.

Don't shy away from showing code, showing things that broke, showing the ugly process. It's encouraging for others to see.

End goal

Well, ideally we have fewer clickbait "5 best React alternatives" articles and more thoughtful pieces intended to teach and educate with a bit of rigor.

It's better for individuals and for companies. It's better for the internet.

Community

If you want a community of folks where you can find encouragement to write and eyes to review drafts, check out the #writing-and-drafts channel on the Software Internals Discord.

Is it worth writing about?

Well if you come to me I'm almost surely going to say yes. Poor Betteridge.