Remix.run Logo
akst 4 days ago

Just confirming, I've seen that the title between the post and link are inconsistent incase there's any confusion.

While I agree, the difference is significant, and it is often the case that a a decent tutorial/blog post on a technology is rarely tailored to non developers

I do think there's a kernel of truth in this for with educational content written by developers. I think many developers underestimate the attention and care that's necessary to write high quality education material. Not to say they shouldn't, it's a valuable skill for everyone to develop but it doesn't always come naturally.

I think one part of it is, in writing the content sometimes someone who is inexperienced in writing, might be writing something with dual roles in mind. They may be venting their frustrations with learning the technology, selling their experience and accomplishments (to any potential employers who may be reading it, which is where some name dropping might be coming in) and using the format of a tutorial as a vehicle to do so. They may also just not have a clear objective of what they want to write in mind and they just want to share some information and they initially wrote a tutorial and veered off on to something else.

If you're someone who is reading something like this, it can actually be annoying or confusing if you went into the tutorial expecting one thing which doesn't end up being there. For a beginner even more so, as you lack the domain knowledge to know if you need to disregard these tangents or skip forward, if you're more experience it feel like someone is wasting your time by telling you they were going to explain X Y Z then it ends up being some rant passing as a half baked tutorial. That said I rather this than AI slop, but reading it can be equally annoying if it feels like the author doesn't respect your time in the way AI slop feels like there's an expectation your time reading it is worth less than the time the author would spent writing it.

The issue here for the reader is usually the content is inconsistent with their expectations, and for the author they possible communicated that poorly.

Yes if the author has mistakenly assumed an article not written for them were written for them, well yes that's on the author. But taking what they say at face value or even the title used at the post I think there is a point of value to take away from this for those writing anything ranging from education material to a post mortem.

Know your objective, the key information your communicating, has the way you've written effectively communicated that to your intended audience? Cull things that detract from this. And of course there's nothing wrong with unstructured forms of writing, they can be really fun, but they are the last thing someone wants to read when they are in the middle of trying to fix a technical issue they don't entirely understand. That can largely be avoided by with a better title, or avoiding insinuating the post is something it's not.