How I, a non-developer, read the tutorial you, a developer, wrote for me
1–10 of 455 posts
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#2Most devs write docs like aliens. Time to send them back to elementary school English class.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#3This is gold
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#4Most 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 why courses and other structured learning materials exist. Beginners have to be nurtured through lots of context that builds up slowly. If every article had to start from scratch, we’d never get to anything interesting. By the time we got to the interesting bit after 30,000 words of preamble, you’d be long gone as a reader.
And the very next reader would complain that the 30,000 words were not enough introduction to the topic. They needed 40,000.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#5Most 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.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#6The funniest part, lol
it might be in library/library/library/llibrary/liiiiiibrarrrary/llllliiiiibrary/hidden/hidden/hiding/you can’t find me/hidden/nope/never/hahahahereiam.file.Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#7But is this tutorial meant for a non developer to read? I would imagine a linguistic psychology tutorial would have the same effect on a dev written by an expert.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#8Most 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.
That doesn't really excuse the strange acerbic brevity [that] I and most of my peers default to when writing technical documentation.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#9I 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 hoobastank without a major gLibc upgrade. I got shamrock talking after compiling the compatibility shim for single-threaded pintafore and migrating from Debian to Fedora 75bit, but then the fistifunk socket closed! A few more hours troubleshooting and eventually figured out the root cause: The Snarfus node's DNS resolver was down. Turned it back on and everything worked perfectly.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#10I 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.