Live data from Hacker News

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

anniemueller.com

21–30 of 455 posts

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

#21
post #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 v…

Entirely 100% true. I can count on one hand the times I've said "wow, this documentation was written by someone who cared". Threejs is a good example here, but even then it is subject to API rot and needless reference chasing.

Examples are often the best way to do documentation, sadly.

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

#22

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.

Emu-laterrrrrr… and Doug.

I would bemoan the effectiveness of the advertising on me, but it’s just nice to see somewhat traditional advertisement styles working in the age of 5 second ads.

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

#23

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

C++ is written by 99% professional architecture astronauts who do fuck all in terms of valuable software. I will die on this hill.

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

#24
post #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…

> If they do know, and you tell them, then you've only really confirmed what they already knew.

Not necessarily. This opens you up to accusations of engaging in "mansplaining" which has broadened in definition over the years.

In addition to this, it opens you up to being thought of as a "know it all".

It's far safer, as far as office politics are concerned, to put on your coworkers the burden of asking you to clarify/explain/teach.

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

#25
post #5

Earlier quoted context omitted.

Most docs I read aren't written for an audience of non-developers.

That doesn't really excuse the strange acerbic brevity [that] I and most of my peers default to when writing technical documentation.

It's impatience and tiredness.

Taking an idea, and converting it into code is a lot of work. Taking that same idea and then taking the code and turning the both into words that can communicate the original idea is just another complex task. I'd wager that the dopamine hit of getting stuff working has worn off and most people are writing doco when they're exhausted from their recent work.

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

#26
post #5
post #2

Most devs write docs like aliens. Time to send them back to elementary school English class.

Most docs I read aren't written for an audience of non-developers.

Most docs I read aren’t written for any audience, imho.

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

#27

Earlier quoted context omitted.

That is the typical experience for C++ tooling lol

C++ is written by 99% professional architecture astronauts who do fuck all in terms of valuable software. I will die on this hill.

HPC?

Windows NT?

GCC?

Video games?

I'm a veteran C programmer with a deep dislike of C++, but to say it's not used for valuable software is just wrong.

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

#28

Earlier quoted context omitted.

That is the typical experience for C++ tooling lol

C++ is written by 99% professional architecture astronauts who do fuck all in terms of valuable software. I will die on this hill.

Linux is a pretty valuable example of such astronautics. Also things like TCP...

I hope you don't die on a hill tho, not anytime soon at least.

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

#29

I guess many tutorials are not made for absolute beginners and they have assumed you have learnt the basics before jumping into their topic. For example, if you never learn programming and set up an ide before, it has no way you can learn OpenGL as your first tutorial, and all the syntax and commands will look alienated.

OpenGL is not so bad because the API is quite stable. WebGL in particular is great because there's literally zero setup you need to do for executing it.

Integrating with Linux/Windows display surfaces is disgusting however. KMSDRM is way, way better than the nightmare that is X11 and Wayland.

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

#30
Most technical writers (and communicators in general) have an insufficient appreciation for the curse of knowledge.

This takes me back to running a World of WarCraft guild as a teenager.

We would organize "raids" maybe 3 to 4 times a week. It involved getting 40 of our guild members from all over the world to sign on at the same time, and spend hours facing off against dragons and other monsters inside dungeons. It was the most fun I'd ever had in a game, but it was also instructive. The battles were famously difficult and required a ton of coordination and strategy, and even a small mistake could get everyone killed. So our policy was that everyone in the raid had to sign onto our Teamspeak server, which was basically an audio-only Zoom call where my appointed officers and I could give orders and dictate strategy.

I very quickly learned an important lesson in communication: assume the worst. Surprisingly (to me at the time), most people who don't understand what you're saying won't stop you to tell you they didn't understand. And so I came to live by two rules:

1. If it's worth saying once, it's worth repeating. Assume people are only half listening, that they're distracted, that they're not paying attention.

2. Don't assume people know what you know. In fact, while talking, keep a second thread running where you explicitly ask yourself, "What am I saying that my listener might not know?" Then explain it.

The more I followed these rules, the better we did on our raids.

But even long after I stopped playing WoW, both of these rules have been helpful. Especially the second one, which helps overcome the curse of knowledge -- the phenomenon that occurs when a person who has specialized knowledge incorrectly assumes that others share in that knowledge.

Thinking about the curse of knowledge when communicating basically becomes second nature after a while. And then it becomes obvious when you observe other communicators who don't care about the curse of knowledge. They confidently launch into stories using obscure terminology and acronyms that nobody understands, without a care in the world for their listeners' understanding, they don't notice at all that nobody understands.

Post reply on HN