Christopher Lemmer Webber is a user on octodon.social. You can follow them or interact with them if you have an account anywhere in the fediverse. If you don't, you can sign up here.
Christopher Lemmer Webber @cwebber

TFW you do an example from the tutorial and it keeps !@$%'ing erroring and you keep trying to figure out what you did wrong

then you read one more line forward and it says "surprisingly this errors and here's why"

· Web · 3 · 13

@cwebber

Yess! Or a hardware tutorial that says "solder this down here!
...

Oh but don't *actually* do that because everything breaks when you do that & then you'll have to order a whole new board, so instead do this..." 😩

@MutoShack Oof! That sounds even worse!

("Luckily" I don't hack hardware, though usually I feel sad about that and not lucky)

@cwebber NOOOO! That is so shitty! I would hunt the author of that howto down.

@gemlog @cwebber surely that should be edited out?

If there really was a useful and specific reason to demonstrate that error, it should be put in a box at the end of the article with a warning, so those who are time pressured do not encounter it - and many people reading shorter tutorials as opposed to a whole "textbook" type teaching course usually are under time pressure..

@vfrmedia @cwebber @MutoShack
No Alex, then it might be ignored and it may be out of context at the end. Your idea would work as a pull quote though. That would be good.
It is simply written upside down.
It should be written as e.g. "here is a gotcha you need to know about so you don't pound your head on the table for hours". Not that exactly, but I'm too lazy to write otherwise right now ;-)
Sheesh. What an asshole that author is.

@gemlog @cwebber @MutoShack

pull quote is the kind of thing I was thinking of, but I had forgot what it was called, and was also recalling 1980s/1990s era computer and electronics books I've read where there was a marker like an asterisk or arrow and/or a paragraph or box (sometimes at the end of the article) containing warnings of this nature (perhaps this is in the days before TL;DR culture...)

@vfrmedia @cwebber @MutoShack

In regular html the rewrite would work, but if I was to make a pdf or something I'd do the pull quote version.

In either case it's way better than the way the jerk wrote that time-wasting howto.