Live data from Hacker News

How I, a non-developer, read the tutorial you, a developer, wrote for me

anniemueller.com

11–20 of 455 posts

Re: How I, a non-developer, read the tutorial you, a developer, wrote for me

#11
post #4

Most tutorials are not for non-developers, they’re for other developers who are also in the ecosystem. They’re more like academic papers (peer-to-peer communication of new discoveries) than they are like a pop sci book or show meant for a general audience. And that’s okay! Great even! As a fellow peer I benefit greatly from those tutorials. Sometimes even from my own notes published and forgotten years ago. This is w…

> Most tutorials are not for non-developers, they’re for other developers who are also in the ecosystem.

To me eye, most tutorial nowadays are so a developer can put "made public contribution to " on their resume or quarterly evaluation rather than helping other developers.

I'd be even happier if the original writer would simply come back 3 months later and retrace their own directions. That would make the tutorial vastly better as they will suddenly see all the little things they left out.

Re: How I, a non-developer, read the tutorial you, a developer, wrote for me

#12

I followed this tutorial but ran into an issue where shamrock portal kept crashing. When I checked the logs, I found it would start a beep but never finish a boop. After a few hours of Googling I discovered my Debian 12's Klingon troglodyte emulator had a known centipede reported in 2013 that's never been squashed because hoobastank 34.100-6x00 actually requires it, and Debian can't move to the newer version of hooba…

Not emulator, emulater. This technical term may also hyphenated, emu-later.

Re: How I, a non-developer, read the tutorial you, a developer, wrote for me

#14
One of the things I've tried to teach people I've mentored over the past few decades is the principle of "Sharing is better than assuming." If you know something, share it with other people. Don't assume that they know something. If they do know, and you tell them, then you've only really confirmed what they already knew. If they don't know whatever it is you've helped them immensely and made whatever it is much more accessible.

Occasionally people will complain that you're being verbose and adding detail that they didn't need but in those cases you can usually just say "oh, that's just in case a [junior|manager|customer] sees it." People don't mind if you flatter them that the explanation was for other people.

It applies as much to development as it does to investment reporting, people management, delivery management, etc,

Re: How I, a non-developer, read the tutorial you, a developer, wrote for me

#15

I followed this tutorial but ran into an issue where shamrock portal kept crashing. When I checked the logs, I found it would start a beep but never finish a boop. After a few hours of Googling I discovered my Debian 12's Klingon troglodyte emulator had a known centipede reported in 2013 that's never been squashed because hoobastank 34.100-6x00 actually requires it, and Debian can't move to the newer version of hooba…

Oh please, this is why it's _clearly_ superior to run Catenary or P. Papua

Re: How I, a non-developer, read the tutorial you, a developer, wrote for me

#18

This is how I, a web developer, feel whenever I'm required to build something using cmake. I guess I need to go read a book about it or something because the instructions seem different every time.

That is the typical experience for C++ tooling lol

Re: How I, a non-developer, read the tutorial you, a developer, wrote for me

#19
When I was at the head of the jailbroken iPhone ecosystem, I put together a tutorial for how to get an SSH daemon set up on their phones. I put a lot of effort into making it something that anyone could follow, step by step, and achieve the result, making sure to skip no steps, assume no knowledge, and with screenshots showing the interface.

I soon thereafter received an e-mail from someone saying that they had excitedly followed my tutorial and found it very easy to follow; but, they had now gotten to the end of the instructions, were staring at some text that said "mobile@iPhone ~$ " (or whatever the default bash prompt was; I do not remember) and they did not know how to proceed.

I had similar experiences over the years, and I had a realization at some point: if you provide someone detailed step-by-step instructions for how to find the dragon, part of the UI/UX of the tutorial should be that you don't actually feel comfortable following it if you should not be doing so: the difficulty of the path must scale with the goal.

This is similar to real-world affordances, FWIW: if a user should not be opening a panel unless they are ready to do maintenance, yes, don't go out of your way to make it hard to service without permanently damaging it (that's evil), but, maybe, screwing the panel shut is more appropriate than providing a pull tab, due to what the latter implies.

A lot of users find this annoying, because they think they want to do X, and they just need better step-by-step instructions... but, that's just not how the world works: a lot of times, what you need to do to do the task is, in fact, a basic knowledge of the entire system, sufficient that you will need a fraction of the instructions (if any).

On the other side it causes another problem, BTW: if you make instructions that anyone can follow--including people who probably aren't at the level where they should do so yet--you also end up with instructions that are more difficult to follow for the people who should be doing so, as they are extremely verbose and often narrow in their scope.

It also sets up perverse incentives to try to make the instructions even easier to follow, well past the level of easiness the task should actually be at, which, again, causes problems for the people you actually want following the tutorial: if you find yourself creating little docker containers to avoid saying "install a compiler"... no.

Re: How I, a non-developer, read the tutorial you, a developer, wrote for me

#20
It's people sharing with others of equivalent skill. Use an LLM to adjust to your skill level. The times I write this it's to document something that worked. There's no guarantee it's what will work for you. You're supposed to translate it. So it's not really written for you.
Post reply on HN