Blog Writing for Developers (2023)(rmoff.net)
rmoff.net
Blog Writing for Developers (2023)
https://rmoff.net/2023/07/19/blog-writing-for-developers/
43 comments
>each blog post helps me think more deeply
The most on point quote I know about this idea: "I don't write to say what I think, but to know what I think." (E. Berl)
Writing can help to become less confused, but being confused can incite to write a lot (J. Joubert: "The supremely false mind is the one that never senses when it goes astray.").
The most on point quote I know about this idea: "I don't write to say what I think, but to know what I think." (E. Berl)
Writing can help to become less confused, but being confused can incite to write a lot (J. Joubert: "The supremely false mind is the one that never senses when it goes astray.").
Although this is related to technical writing it is also similar to one of the ideas in "A theory as to why Art is created" https://medium.com/luminasticity/a-theory-as-to-why-art-is-c...
>the creation exists afterwards, and is thus available as a form of mnemonic for the creator. They can revisit and re-experience that sensation of creation that would otherwise have been transitory.
Other parts suggest that the literary writer writes to sharpen and go deeper into the experience of thinking, to extend it.
The two ideas seem related.
>the creation exists afterwards, and is thus available as a form of mnemonic for the creator. They can revisit and re-experience that sensation of creation that would otherwise have been transitory.
Other parts suggest that the literary writer writes to sharpen and go deeper into the experience of thinking, to extend it.
The two ideas seem related.
Yes, avoid pronouns. Right to remove them.
I often write blog posts only to never publish them because they served their purpose (and I'm too lazy to edit them until they make for a nice read).
My number one productivity tip for blogging is to lower your standards. Don't hold onto a piece until you think it's good enough - always publish when you know that there are improvements you could still make.
The alternative is a folder full of drafts and never publishing anything at all.
With the exception of egregious errors none of your readers will ever know how much better your piece of writing could have been.
The alternative is a folder full of drafts and never publishing anything at all.
With the exception of egregious errors none of your readers will ever know how much better your piece of writing could have been.
I don’t think the original comment you’re replying to was about productivity. I agree with the original comment - 99% of what I write is for the purpose of making sense of things. They aren’t for external consumption, and never will be. Writing for oneself is entirely different than writing for others
This is kinda similar to never open-sourcing some useful proof-of-concept software, because of the percieved need to polish, test and document it
Also the perceived need of (not) being useful. I don't feel the need to have all my stuff out there. That's as true for many of my unpublished blog posts as it is for many of my unreleased projects.
The world doesn't need another sudoku solver, and I don't think mine is any better than the thousands already out there. The same is true for my unpublished rants or my unpublished howtos.
The world doesn't need another sudoku solver, and I don't think mine is any better than the thousands already out there. The same is true for my unpublished rants or my unpublished howtos.
That tracks for me. My most read blog posts were howtos I wrote for my own future documentation.
The author suggests everyone should watch the Larry McEnerney lecture but he seems to have missed a pretty important point from that lecture.
A really big point Larry tries to make during his lecture is that there are 2 types of writing. One you do for yourself (to help clear your ideas) and the other and the other one is designed to valuable to the reader.
And he is pretty obsessed with the idea of writing valuable text. He even says that if your text isn't valuable there is no point in making it persuasive, organized or clear.
For me this was a pretty interesting revelation. For most of my life I had this idea that the quality of the content and the quality of the writing were tightly related. And this idea made me believe that if you have good content, good writing should follow naturally.
After watching this lecture I realized that content and writing are separated axis, and you can definitely have one without the other. LLMs are pretty good at writing without content, for example.
A really big point Larry tries to make during his lecture is that there are 2 types of writing. One you do for yourself (to help clear your ideas) and the other and the other one is designed to valuable to the reader.
And he is pretty obsessed with the idea of writing valuable text. He even says that if your text isn't valuable there is no point in making it persuasive, organized or clear.
For me this was a pretty interesting revelation. For most of my life I had this idea that the quality of the content and the quality of the writing were tightly related. And this idea made me believe that if you have good content, good writing should follow naturally.
After watching this lecture I realized that content and writing are separated axis, and you can definitely have one without the other. LLMs are pretty good at writing without content, for example.
My biggest challenge with writing blogs/newsletters is the fear of publishing, not getting it "perfect", or being horribly wrong about whatever I'm writing about.
To get over this I just made simple personal blog/site using GH pages/jekyll/markup that doesn't have 1. A marketing version of a "publish" function and 2. the posts are perpetually in DRAFT.
Basically there is no 'done' which leaves me more comfortable in putting my thoughts on the internet instead of leaving them in my head. I can keep going back to the ideas and refining them.
To get over this I just made simple personal blog/site using GH pages/jekyll/markup that doesn't have 1. A marketing version of a "publish" function and 2. the posts are perpetually in DRAFT.
Basically there is no 'done' which leaves me more comfortable in putting my thoughts on the internet instead of leaving them in my head. I can keep going back to the ideas and refining them.
I can relate.
However, something to remember is that, even when you're right, you'll still be wrong to many people on the internet.
My biggest barrier to getting back into blogging is the low return on investment. Absolutely nobody I know outside of developers on HN actually reads blogs today. Everyone seems to rely on YouTube/TikTok, ChatGPT, mainstream news articles, and maybe whatever blogspam The Google decides to surface. The days of "if you build it they will come" are long since dead, and even if I were to find regular readers, is it really worth my time to entertain or inform them when I could be out fishing on my boat?
However, something to remember is that, even when you're right, you'll still be wrong to many people on the internet.
My biggest barrier to getting back into blogging is the low return on investment. Absolutely nobody I know outside of developers on HN actually reads blogs today. Everyone seems to rely on YouTube/TikTok, ChatGPT, mainstream news articles, and maybe whatever blogspam The Google decides to surface. The days of "if you build it they will come" are long since dead, and even if I were to find regular readers, is it really worth my time to entertain or inform them when I could be out fishing on my boat?
I agree with you, but just for kicks I'd like to go through your examples.
First, blogging is alive and well in the outdoor sports space. "Trip reports" serve as incredibly helpful tools for research. In climbing, [Steph Abegg](https://www.stephabegg.com/tripreports/chronology) has one of the most useful sites cataloging, detailing, and photo logging all of her ascents. The late Marc-Andre Leclerc was a beautiful human, and while there are films and memories about him, it's his [blog](https://marcleclerc.blogspot.com/) that allows the world to get a truer sense for who he was.
I'm probably in the minority, but I prefer blogs over YouTube for their ability to parse the info more easily. TikTok takes most of the control in how it presents any info you might find and tops it off with immeasurable distraction.
ChatGPT can be great for quickly gathering relevant knowledge, but it still needs cross-referencing, and lacks the creative and novel elements that comes from a valuable human blog post.
Mainstream news articles tend to lack personality and voice.
"If you build it they will come" seems to still hold true for the posts and trip reports I've written. I've been pleasantly surprised by the email I've receive in my inbox asking esoteric follow-up questions, wondering how they even found my posts in the first place.
Overall traffic is admittedly mostly non-existent, and that's fine as I'd be glad to help or inform the few that do come across my posts. Though more to your point, I do wonder how many potential (younger?) readers will never come across a blog post because it's not ingrained as a place to look for info, as opposed to YouTube/TikTok etc.
First, blogging is alive and well in the outdoor sports space. "Trip reports" serve as incredibly helpful tools for research. In climbing, [Steph Abegg](https://www.stephabegg.com/tripreports/chronology) has one of the most useful sites cataloging, detailing, and photo logging all of her ascents. The late Marc-Andre Leclerc was a beautiful human, and while there are films and memories about him, it's his [blog](https://marcleclerc.blogspot.com/) that allows the world to get a truer sense for who he was.
I'm probably in the minority, but I prefer blogs over YouTube for their ability to parse the info more easily. TikTok takes most of the control in how it presents any info you might find and tops it off with immeasurable distraction.
ChatGPT can be great for quickly gathering relevant knowledge, but it still needs cross-referencing, and lacks the creative and novel elements that comes from a valuable human blog post.
Mainstream news articles tend to lack personality and voice.
"If you build it they will come" seems to still hold true for the posts and trip reports I've written. I've been pleasantly surprised by the email I've receive in my inbox asking esoteric follow-up questions, wondering how they even found my posts in the first place.
Overall traffic is admittedly mostly non-existent, and that's fine as I'd be glad to help or inform the few that do come across my posts. Though more to your point, I do wonder how many potential (younger?) readers will never come across a blog post because it's not ingrained as a place to look for info, as opposed to YouTube/TikTok etc.
I mean if your goal is to be internet famous, have lots of followers in the tech space then yeah there are plenty of people doing that on Youtube.
I suspect a lot of junior devs set up blogs more as an experiment in setting up a linux server, static site generator, experimenting with Go/Rust/Ruby/PHP or whatever. Most lose interest when they realise the vast majority of people out there just aren't interested in their content and they get demotivated.
To me personally the word "blog" always sounds like something unpleasant somebody before you left in a toilet for you to discover. It's a shitty sounding word.
I suspect a lot of junior devs set up blogs more as an experiment in setting up a linux server, static site generator, experimenting with Go/Rust/Ruby/PHP or whatever. Most lose interest when they realise the vast majority of people out there just aren't interested in their content and they get demotivated.
To me personally the word "blog" always sounds like something unpleasant somebody before you left in a toilet for you to discover. It's a shitty sounding word.
Well put, I also did exactly this. It’s just markdown, as soon as I deploy it’s live, no publish step.
I’m writing to help myself get better at technical communication and to solidify the concepts in my own head in depth.
I’m writing to help myself get better at technical communication and to solidify the concepts in my own head in depth.
What helps me is realizing that basically no one is every going to read what I write. And if they do actually read it, then that's a good problem to have.
The lecture by Larry McEnerney was a great recommendation, I just watched. When I was in college I had a revelation reading Clarity: Toward Style and Grace by Williams. Really put into concrete terms why some ways of writing "sound wrong" and how to avoid them.
Seconding this — I know a 1h20m video seems like a commitment, but it's worth it! Do not skip the lecture video!
> The second reason that I’ll write is to learn about something. It’s one thing to hand-wave one’s way through a presentation. It’s another to commit pen to paper (well, bytes to disk) and explain something. Quite often I’ll realise that there’s a gap—or gaps—in my knowledge that I need to explore first before I can properly write about something, and that’s the very reason that I do it.
This is a very good reason to write - I've learned about a ton of topics over the years at depths I wouldn't have bothered with if I weren't going to write blogposts about it. I really didn't need to spend a year chewing through other people's PhD work to understand some of the quirks of lead acid battery behavior I was seeing years back (Steve on IRC's description covered the details well enough to work around it), but if I was going to write it up[0], I wanted to actually understand it. And that took time.
But it misses one of the most important reasons I write: To force myself to finish projects and document things, so I can fully offload it from my brain.
I'm very prone to "90% done, eh, good enough, I'll finish it later..." sort of projects, and they take up a lot of mental space because I still have to (or, at least, try to...) remember state on the project. Before I write about something, I want it fully done, and then as part of writing it up, I trust myself to document anything weird, any odd findings, etc. Once I've done that, then I can entirely forget the details of the project, teardown, or whatever, knowing that if I need to do it again, I can go reference my old writeup and I'll know what I need to do!
Once written, I can just clear the brain-space out, and not worry about forgetting about it, because it's been written up, by me, in my style.
Also, copy editors and reviewers start to sound more like professional writing than "blogging," at least to me.
[0]: https://www.sevarg.net/2018/04/08/off-grid-rv-lead-acid-main...
This is a very good reason to write - I've learned about a ton of topics over the years at depths I wouldn't have bothered with if I weren't going to write blogposts about it. I really didn't need to spend a year chewing through other people's PhD work to understand some of the quirks of lead acid battery behavior I was seeing years back (Steve on IRC's description covered the details well enough to work around it), but if I was going to write it up[0], I wanted to actually understand it. And that took time.
But it misses one of the most important reasons I write: To force myself to finish projects and document things, so I can fully offload it from my brain.
I'm very prone to "90% done, eh, good enough, I'll finish it later..." sort of projects, and they take up a lot of mental space because I still have to (or, at least, try to...) remember state on the project. Before I write about something, I want it fully done, and then as part of writing it up, I trust myself to document anything weird, any odd findings, etc. Once I've done that, then I can entirely forget the details of the project, teardown, or whatever, knowing that if I need to do it again, I can go reference my old writeup and I'll know what I need to do!
Once written, I can just clear the brain-space out, and not worry about forgetting about it, because it's been written up, by me, in my style.
Also, copy editors and reviewers start to sound more like professional writing than "blogging," at least to me.
[0]: https://www.sevarg.net/2018/04/08/off-grid-rv-lead-acid-main...
As a reader, people writing to learn about something irritates me when it's not clearly flagged that the writer has almost zero experience using the thing they are writing about.
There's so many articles in tech where the writer probably has less experience with something than literally anyone who will read their post, and it means there's effectively a content farm of what a new software engineer will learn in their first few months (if not years) on the job, written by software engineers in their first few months, with effectively no net information.
There's so many articles in tech where the writer probably has less experience with something than literally anyone who will read their post, and it means there's effectively a content farm of what a new software engineer will learn in their first few months (if not years) on the job, written by software engineers in their first few months, with effectively no net information.
I'll offer the opposite perspective. People writing about stuff that they are currently learning is often better, because they have a much clearer model of what's obvious and what isn't.
Someone with 20 years of experience with a technology will usually have a much harder time re-connecting with that beginner's mindset and doing a great job of providing the information that other newcomers most need to understand.
That's not to say that there isn't plenty of junk content out there, but I blame that more on inexperienced writers than on people who are writing about technology that they don't have a great deal of experience with.
A great writer should be able to write about something while they're learning while still producing content that's genuinely useful.
Someone with 20 years of experience with a technology will usually have a much harder time re-connecting with that beginner's mindset and doing a great job of providing the information that other newcomers most need to understand.
That's not to say that there isn't plenty of junk content out there, but I blame that more on inexperienced writers than on people who are writing about technology that they don't have a great deal of experience with.
A great writer should be able to write about something while they're learning while still producing content that's genuinely useful.
But they should still present themselves accurately, because at that stage they don't know what they don't know and they may be misleading people without realizing it.
This is why I like the TIL format. Saying "Today I Learned" is a great shorthand for "I'm not an expert and I may have missed something but here's what I've figured out so far..."
One could be skeptical and not take everything written on the internet as the source of truth.
I like to utilise the socratic method while reading about something, I want to understand deeply.
I like to utilise the socratic method while reading about something, I want to understand deeply.
There are some topics that we need more expert voices on, because the subject matter is genuinely complicated and requires a veteran hand to guide people through. Otherwise we end up with a bunch of "expert beginners" sitting on their local maxima of understanding and thinking they are at the pinnacle of understanding. Some of us really do want to hear how experts think, imperfect as their explanations may be. Dev-fluencers are already taking over the space with their absolute nonsense gish-galloped everywhere for that sweet YouTube $$$
huh, dev-fluencers, I worked briefly with one and I never knew there was a name for what he did, gish-galloped. Amazing.
“The curse of knowledge” is what you’re describing
I imagine you are speaking of the trend of medium like articles where someone writes a "guide" on how to use a trendy tool rather than a blog post about something someone did with a tool. It is why I usually ignore anything on a blogging platform.
I LOVE reading dev blogs about the journey of making something. I understand the frustrations when you know they are doing it "wrong". But, more often than not, for me at least, I always learn something new.
I LOVE reading dev blogs about the journey of making something. I understand the frustrations when you know they are doing it "wrong". But, more often than not, for me at least, I always learn something new.
Writing, I think, is the root of learning + thinking deeply.
No matter what subject (tech, travel blogging), writing forces you to organize and solidify your thoughts.
Bonus points when you do so in public, where you are open to scrutiny.
No matter what subject (tech, travel blogging), writing forces you to organize and solidify your thoughts.
Bonus points when you do so in public, where you are open to scrutiny.
I've been writing / editing technical blogs for the past decade, and I found that the key thing is to be engaging.
Most technical blog posts are boring. They look like documentation.
My best technical blog posts were the ones where I added personal stories about how I used the library/framework I was referring to.
The best advice from OP is to hire an editor. Especially for non-native English speakers (like me). A good editor can transform "good" technical content into exceptional content.
Michael Lynch, who regularly front-page HN has a great article about this: https://mtlynch.io/editor/
Most technical blog posts are boring. They look like documentation.
My best technical blog posts were the ones where I added personal stories about how I used the library/framework I was referring to.
The best advice from OP is to hire an editor. Especially for non-native English speakers (like me). A good editor can transform "good" technical content into exceptional content.
Michael Lynch, who regularly front-page HN has a great article about this: https://mtlynch.io/editor/
Is there an easy way to setup a blog that supports syntax highlighting, images, quotes, latex, but without going in depth? I'd love to host a blog, but I'd rather invest most of the time into the writing.
I've loved Astro [0] for my blog [1]. You get a lot for free and you can tinker as much or as little as you like.
It renders to static HTML/CSS (unless you _want_ JS) and it feels lightweight. You can start with a plain unthemed site today and slowly add features/polish when you feel like procrastinating on writing :)
[0]: https://docs.astro.build/en/tutorial/0-introduction/
[1]: https://github.com/shepherdjerred/sjer.red
It renders to static HTML/CSS (unless you _want_ JS) and it feels lightweight. You can start with a plain unthemed site today and slowly add features/polish when you feel like procrastinating on writing :)
[0]: https://docs.astro.build/en/tutorial/0-introduction/
[1]: https://github.com/shepherdjerred/sjer.red
I'm a happy Zola [0] user, which does everything you mentioned except LaTeX.
There are a few themes [1], though I ended up writing my own [2] (which supports MathJax [3] for mathematical notation).
[0]: https://www.getzola.org/
[1]: https://www.getzola.org/themes/
[2]: https://github.com/welpo/tabi
[3]: https://www.mathjax.org/
There are a few themes [1], though I ended up writing my own [2] (which supports MathJax [3] for mathematical notation).
[0]: https://www.getzola.org/
[1]: https://www.getzola.org/themes/
[2]: https://github.com/welpo/tabi
[3]: https://www.mathjax.org/
I am using Hugo since 2019. Prior to that Jekyll. Both will handle what you want! I am not sure about tex markup because I have not tried to use it since grad school but seems like a good idea to look into.
Are you open to do it with Node? I wrote a blog post[0] with a fairly easy setup. If you're using markdown and any markdown processor you should be good to go.
[0] https://www.itzami.com/blog/how-to-build-a-blog-with-nodejs
[0] https://www.itzami.com/blog/how-to-build-a-blog-with-nodejs
I'm working on a blog platform with those features, it's in closed alpha right now. Drop me a line if you would like to be an early user, my email is in my profile. You'll keep the service for free now, and even after it goes public in exchange for feedback and bug reporting.
Hugo!
Making your own is fun, though.
How do I find good reviewers/editors for my blog? Does anyone have recommendations?
I'm strongly against AI for any writing since it smothers the author's voice into something that sounds generic and lifeless.
I'm strongly against AI for any writing since it smothers the author's voice into something that sounds generic and lifeless.
I am working on writing blog posts, struggling, but still trying. My hope is that it will help me communicate better. My first posts have been...meh.
I've also had situations come up again and don't always immediately remember how I resolved it last time.
I've also had situations come up again and don't always immediately remember how I resolved it last time.
I use my blog (https://codereviewvideos.com/) for a combination of sharing / remembering solutions to weird / interesting technical problems, and for documenting my learning.
Just hit publish.
Most of the time you get absolutely no feedback. Heck, most of the time you get absolutely no views!
But sometimes you will get some feedback. And sometimes that feedback is nasty. So you put that in the bin.
Occassionally someone will contribute a really useful and interesting comment, maybe months after you wrote something (and completely forgot about), which can lead to all sorts of places. I've kept in regular contact with several commenters, and when they share their blogs I go there and comment, too. It's like the olden days of link wheels and what-not, instead of the forced "go comment for back links" the web has become in more recent years.
I blog loads - https://cyclingindoors.co.uk/ is another one, tracking my fitness. It's one of the best things I've ever done.
Seriously, just hit publish!
Just hit publish.
Most of the time you get absolutely no feedback. Heck, most of the time you get absolutely no views!
But sometimes you will get some feedback. And sometimes that feedback is nasty. So you put that in the bin.
Occassionally someone will contribute a really useful and interesting comment, maybe months after you wrote something (and completely forgot about), which can lead to all sorts of places. I've kept in regular contact with several commenters, and when they share their blogs I go there and comment, too. It's like the olden days of link wheels and what-not, instead of the forced "go comment for back links" the web has become in more recent years.
I blog loads - https://cyclingindoors.co.uk/ is another one, tracking my fitness. It's one of the best things I've ever done.
Seriously, just hit publish!
>But sometimes you will get some feedback. And sometimes that feedback is nasty.
Hopefully I wont be one of these, but why do you use bad AI images as the most prominent piece in your posts ?
I've read one post and its not bad, but the images you use just really put me off. They give the felling of 'cheap'/'low effort', which is not an accurate representation of the text you wrote.
If that is an intentional stylistic choice, you should make it more clear to the reader. Maybe add a tagline to your blog? Adjust the theme? Or maybe add something in the text to make it clear why you made that choice.
In a sense using these kind of images is almost like a 'reverse clickbait', where you hide good content behind a really off-putting image and this prevents some from reaching the content you created. Personally, when I see bad AI images I just assume the text will be just a copy and paste from ChatGPT so I generally don't bother reading it.
This is not a rant against AI. I think you could have the same situation using bad stock images, for example.
Hopefully I wont be one of these, but why do you use bad AI images as the most prominent piece in your posts ?
I've read one post and its not bad, but the images you use just really put me off. They give the felling of 'cheap'/'low effort', which is not an accurate representation of the text you wrote.
If that is an intentional stylistic choice, you should make it more clear to the reader. Maybe add a tagline to your blog? Adjust the theme? Or maybe add something in the text to make it clear why you made that choice.
In a sense using these kind of images is almost like a 'reverse clickbait', where you hide good content behind a really off-putting image and this prevents some from reaching the content you created. Personally, when I see bad AI images I just assume the text will be just a copy and paste from ChatGPT so I generally don't bother reading it.
This is not a rant against AI. I think you could have the same situation using bad stock images, for example.
I once heard a senior developer say, 'I’m not shy to admit that after I finish a blog post, I’m at ease to forget about it—because I know I can always look it up again.