[HN Gopher] Blog Writing for Developers (2023)
___________________________________________________________________
Blog Writing for Developers (2023)
Author : mooreds
Score : 228 points
Date : 2024-11-04 20:01 UTC (1 days ago)
(HTM) web link (rmoff.net)
(TXT) w3m dump (rmoff.net)
| Syonyk wrote:
| > _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...
| richardwhiuk wrote:
| 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.
| simonw wrote:
| 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.
| stogot wrote:
| "The curse of knowledge" is what you're describing
| syndicatedjelly wrote:
| 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 $$$
| rustystump wrote:
| huh, dev-fluencers, I worked briefly with one and I never
| knew there was a name for what he did, gish-galloped.
| Amazing.
| Groxx wrote:
| 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.
| no-exist wrote:
| 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.
| simonw wrote:
| 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..."
| rustystump wrote:
| 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.
| ngriffiths wrote:
| 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.
| jakelazaroff wrote:
| Seconding this -- I know a 1h20m video seems like a commitment,
| but it's worth it! Do not skip the lecture video!
| kkdai wrote:
| I've been writing a technical blog for over 20 years, and I
| believe that each blog post helps me think more deeply, examining
| every source and related code carefully. This process has been
| incredibly valuable to me, and even in the LLM era of 2024, I
| still enjoy blogging. Often, the primary user of my blog is
| myself; I go back to my past entries to help guide further
| research and exploration.
|
| 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.
| jffhn wrote:
| >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.").
| bryanrasmussen wrote:
| 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.
| workflowing wrote:
| Yes, avoid pronouns. Right to remove them.
| elric wrote:
| 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).
| simonw wrote:
| 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.
| kstrauser wrote:
| That tracks for me. My most read blog posts were howtos I wrote
| for my own future documentation.
| freilanzer wrote:
| 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.
| bool3max wrote:
| Hugo!
| freetonik wrote:
| 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.
| rietta wrote:
| 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.
| BoingBoomTschak wrote:
| Making your own is fun, though.
| welpo wrote:
| 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/
| itzami wrote:
| 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
| shepherdjerred wrote:
| 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
| inSenCite wrote:
| 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.
| theappsecguy wrote:
| 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.
| ravenstine wrote:
| 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?
| yoyohello13 wrote:
| 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.
| hk1337 wrote:
| 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.
| a6chris wrote:
| 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!
| game_the0ry wrote:
| 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.
| ksahin wrote:
| 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/
| shepherdjerred wrote:
| 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.
| nzach wrote:
| 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.
___________________________________________________________________
(page generated 2024-11-05 23:01 UTC)