I wonder if there's just a mismatch in what 'a beginner' means. Perhaps the tutorial is aimed at beginners _in this specific topic_ ? I have also read 'intro to x' tutorials and had to do a lot of wider reading, I just accept that's the cost of trying something outside my area of knowledge.
How I, a non-developer, read the tutorial you, a developer, wrote for me
101–110 of 455 posts
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#102I don't get it. I learnt to program from tutorials in the early 2000s. I guess at some point in my education I also learnt how to look stuff up. It turns out that was the real skill all along, I guess. So the question is why do people find looking stuff up so difficult? Can you imagine how long every tutorial would be if it started from the bottom? "If you want to make an apple, you must first invent the universe."
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#103I mean, if it reads like that, if probably wasn't meant for you. Which is fine, internet has a lot of content for the most obscure niches
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#104I find that a lot of project homepages (or GitHub README.md these days) are riding high on "if you're reading this, you already know what this is for" energy. What I would give for people to approach documentation in a more empathetic way; tell me what something is for, what problem it solves vs other competing solutions such as X or Y, whether it's still the best solution or in maintenance mode because another tool…
This issue with READMEs in particular has driven me nuts for the decade I've been doing ROS related robotics stuff. So many repos where the only surface clue (i.e. before diving into the code) of what it does is your interpretation of its name. But I'm pretty sure it's universal, like you allude to. And not just open-source; but at work, too. I feel like I'm the only one in my company that makes PRs to edit the READM…
Lately I’ve been asking Cursor “what does the program do?” Was actually pretty helpful as a starting point.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#105Can't recommend this approach highly enough: have someone with minimal expertise go through your docs with the goal of achieving the goal of the docs. Sit next to them or screenshare. Do not speak to them, certainly do not help, just watch. Watch them fumble. Watch them not know what to do. Watch them experience things you (the author) didn't, because you already had xyz configured on your machine and you forgot user…
I'm a Jr. sysadmin at a medium sized software company.
Whenever I document workflows for our users, I have two colleagues of mine who have no connection to IT work through them and add the small gotchas they asked me to the docs.
It saved me a whole bunch of headaches for when other users get enrolled in these workflows.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#106The 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.
sususudododo baby shark
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#107Can't recommend this approach highly enough: have someone with minimal expertise go through your docs with the goal of achieving the goal of the docs. Sit next to them or screenshare. Do not speak to them, certainly do not help, just watch. Watch them fumble. Watch them not know what to do. Watch them experience things you (the author) didn't, because you already had xyz configured on your machine and you forgot user…
I worked with someone who was great with this. They’d go through the docs and do exactly what was said, document where problems were hit and then repeat from scratch again and again. Seemed slow but their docs were excellent and I’m sure it saved more time having him hit each thing once than everyone else hitting them loads.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#108Ironic that 5 years from now we will yearn for the era of human-written tutorials.
You are right but the fact that it will be harder to distinguish between human written and AI written text means that we will be looking for signs that indicate a human written text and will tend to prefer humanly mistakes over AI perfect tutorial.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#109Most 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" That has been repeated in the comments many times now, but the very headline says that this tutorial was indeed also intended for non developers. Like some open source Github project that the author merely wanted to install, not starting to mess with the code. Basically, it is complaining in a satirical way about installation readmes, that maybe they could be made easier, t…
> "That has been repeated in the comments many times now, but the very headline says that this tutorial was indeed also intended for non developers"
tbf, that's not how I read the headline. The headline is: "How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner"
The author is a beginner, which puts them in the field - so the parent comment is valid no?
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#110This article doesn't hit any nail on it's head. Tutorials and instructions of software are of the best quality they have ever been.